> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt > Use this file to discover all available pages before exploring further. # List jobs > Lists the company's jobs. Two modes: - **Day list** (none of limit, skip, createdSince, updatedSince, progress): the jobs of one day, `date` or today in the caller's time zone, ordered by route position, at most 5,000. Archived jobs only with includeArchived=true. - **Paged list** (any of limit, skip, createdSince, updatedSince, progress): all dates unless `date` is given, newest first (by last save, or by creation with createdSince), `limit` default 100, with totalCount and hasMore. Archived jobs are left out unless includeArchived=true. Deleted jobs never come back. Looking up by `id` or `externalId` returns the job whatever its archive status and ignores date and assignee; no match gives an empty list. Workers without the company setting workersViewJobCalendar may only list today (give or take four hours); other dates give 403. ## OpenAPI ````yaml v1/openapi.json GET /jobs openapi: 3.1.0 info: title: Hellotracks REST API version: '1' description: >- Plain REST resources over HTTPS, for tools, automations and services. The ht command line is built on it. contact: email: api@hellotracks.com servers: - url: https://api.hellotracks.com/v1 security: - ApiKey: [] tags: - name: Sign-up and sign-in description: >- Create a company or get an API key by an emailed code, without a key; and check which account a key belongs to. - name: Company description: The company the API key belongs to, with its settings and teams. - name: Members description: 'The people in the company: admins, operators and workers.' - name: API keys description: 'The company''s API keys: list, create, revoke and delete.' - name: Jobs description: 'Jobs: work at a location on a date, assigned to a member.' - name: Places description: 'Places: customer sites and other saved locations with a check-in radius.' - name: Zones description: 'Zones: the company''s geofences.' - name: Routing description: Route optimization for one member's day. - name: ETA pages description: >- Live ETA pages (eta.page links) that show a job's recipient when the worker arrives. - name: Maps description: Rendered maps as GeoJSON, and public map share links. - name: Timesheets description: Clock-in and clock-out entries of members, with totals, and editing them. - name: Forms description: >- Form templates, submitted forms, attachments for file and image fields, and forms linked to places and jobs. - name: Alerts description: >- Alert rules (configs) that watch members, places and zones, and the alerts (instances) they raised. - name: Reports description: >- Reports: the newer reporting API (catalog, preview, run, saved) and the older one (types, generate, jobs, uploads, recurring). - name: Webhooks description: URLs Hellotracks calls when jobs, check-ins, clock-ins or alerts happen. paths: /jobs: get: tags: - Jobs summary: List jobs description: >- Lists the company's jobs. Two modes: - **Day list** (none of limit, skip, createdSince, updatedSince, progress): the jobs of one day, `date` or today in the caller's time zone, ordered by route position, at most 5,000. Archived jobs only with includeArchived=true. - **Paged list** (any of limit, skip, createdSince, updatedSince, progress): all dates unless `date` is given, newest first (by last save, or by creation with createdSince), `limit` default 100, with totalCount and hasMore. Archived jobs are left out unless includeArchived=true. Deleted jobs never come back. Looking up by `id` or `externalId` returns the job whatever its archive status and ignores date and assignee; no match gives an empty list. Workers without the company setting workersViewJobCalendar may only list today (give or take four hours); other dates give 403. operationId: listJobs parameters: - name: id in: query required: false schema: type: string description: Only this job. - name: externalId in: query required: false schema: type: string description: >- Only the job with this externalId. No match returns an empty list with totalCount 0. - name: date in: query required: false schema: type: string format: date description: >- Day of the jobs, YYYY-MM-DD. An empty value lists jobs without a date. Default: today in the day list, all dates in the paged list. - name: allDates in: query required: false schema: type: boolean default: false description: Search across all dates (used with text). - name: assigneeId in: query required: false schema: type: string description: >- Only jobs of this member. An empty value lists unassigned jobs. Not together with assigneeUsername. - name: assigneeUsername in: query required: false schema: type: string description: >- Only jobs of the member with this username. An empty value lists unassigned jobs. Not together with assigneeId. - name: progress in: query required: false schema: $ref: '#/components/schemas/JobProgress' description: Only jobs in this progress state. Switches to the paged list. - name: text in: query required: false schema: type: string description: >- Case-insensitive search in title, address and notes; also matches a job id, an order number or a job group name. - name: createdSince in: query required: false schema: type: integer format: int64 description: >- ms timestamp: only jobs created at or after it, newest created first. Switches to the paged list. - name: updatedSince in: query required: false schema: type: integer format: int64 description: >- ms timestamp: only jobs saved at or after it. Switches to the paged list. - name: includeArchived in: query required: false schema: type: boolean default: false description: Include archived jobs. - name: limit in: query required: false schema: type: integer default: 100 minimum: 0 description: Page size of the paged list. Switches to the paged list. - name: skip in: query required: false schema: type: integer default: 0 minimum: 0 description: Jobs to skip in the paged list. Switches to the paged list. responses: '200': description: Success content: application/json: schema: type: object required: - data - error - meta properties: data: $ref: '#/components/schemas/JobList' error: type: 'null' meta: $ref: '#/components/schemas/Meta' example: data: items: - id: '650000000000000000000001' externalId: ORDER-1001 title: Install water heater address: 500 Market St, San Francisco, CA 94105 notes: Ring at the side door. issueText: '' createdAt: 1793520000000 updatedAt: 1793523600000 scheduledAt: 0 assignedAt: 1793520000000 acceptedAt: 0 completedAt: 0 failedAt: 0 progress: scheduled date: '2026-11-02' priority: 2 timeWindow: start: '09:00' end: '12:00' onSiteDurationSeconds: 3600 location: lat: 37.7897 lng: -122.4 assignee: id: a1b2c3 username: alex@example.com name: Alex Rivera email: alex@example.com phone: '+14155550101' placeId: p1q2r3 contact: name: Sam Lee phone: '+14155550102' email: sam@example.com customFields: PO: '4711' linkedForms: - id: f1a2b3 title: Install checklist etaSessionId: eta_k7m2p9x4q8r3 etaUrl: https://eta.page/K7M2-P9X4-Q8R3 totalCount: 1 hasMore: false error: null meta: path: /v1/jobs method: GET '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: JobProgress: type: string enum: - unassigned - scheduled - accepted - in_progress - success - failed description: >- Derived from the job's timestamps: success when completed, failed when marked failed, in_progress when accepted and checked in, accepted when accepted, unassigned when nobody is assigned, otherwise scheduled (assigned, not yet accepted). JobList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Job' totalCount: type: integer description: >- Number of matching jobs over all pages. Present for paged or searched lists (limit, skip, createdSince, updatedSince, progress, text or allDates), and for an externalId without a match. hasMore: type: boolean description: >- true when skip + items < totalCount. Present together with totalCount. Meta: type: object properties: path: type: string description: The request path, without /v1. example: /jobs method: type: string example: GET Job: type: object required: - id - progress - timeWindow - location - assignee - contact - customFields - linkedForms properties: id: type: string description: Job id (24 hex characters). externalId: type: string description: Your own id for the job; left out when not set. title: type: string address: type: string notes: type: string description: Notes from the dispatcher to the worker. issueText: type: string description: Text the worker entered on the job. createdAt: type: integer format: int64 description: ms timestamp. updatedAt: type: integer format: int64 description: >- ms timestamp: the latest of saved, created, assigned, accepted, scheduled, check-in, check-out, failed and completed. scheduledAt: type: integer format: int64 description: ms timestamp, 0 when not set. assignedAt: type: integer format: int64 description: ms timestamp, 0 when not set. acceptedAt: type: integer format: int64 description: ms timestamp, 0 when not accepted. completedAt: type: integer format: int64 description: ms timestamp of success, 0 when not completed. failedAt: type: integer format: int64 description: ms timestamp of failure, 0 when not failed. progress: $ref: '#/components/schemas/JobProgress' status: type: string enum: - archived - deleted description: >- Only on archived or deleted jobs; normal jobs have no status. A deleted job only shows up in the answer to a create whose externalId matches it. date: type: - string - 'null' format: date description: YYYY-MM-DD, null when the job has no date. priority: type: integer minimum: 0 maximum: 10 timeWindow: $ref: '#/components/schemas/JobTimeWindow' onSiteDurationSeconds: type: integer minimum: 0 location: $ref: '#/components/schemas/JobLocation' assignee: $ref: '#/components/schemas/JobAssignee' placeId: type: string description: The place the job belongs to; left out when none. contact: $ref: '#/components/schemas/JobContact' customFields: type: object additionalProperties: type: string description: Custom field names and values. linkedForms: type: array items: $ref: '#/components/schemas/JobLinkedForm' etaSessionId: type: string description: >- Id of the job's active ETA session (not revoked, not expired); left out when there is none. etaUrl: type: string format: uri description: Public eta.page link of that session; left out when there is none. example: id: '650000000000000000000001' externalId: ORDER-1001 title: Install water heater address: 500 Market St, San Francisco, CA 94105 notes: Ring at the side door. issueText: '' createdAt: 1793520000000 updatedAt: 1793523600000 scheduledAt: 0 assignedAt: 1793520000000 acceptedAt: 0 completedAt: 0 failedAt: 0 progress: scheduled date: '2026-11-02' priority: 2 timeWindow: start: '09:00' end: '12:00' onSiteDurationSeconds: 3600 location: lat: 37.7897 lng: -122.4 assignee: id: a1b2c3 username: alex@example.com name: Alex Rivera email: alex@example.com phone: '+14155550101' placeId: p1q2r3 contact: name: Sam Lee phone: '+14155550102' email: sam@example.com customFields: PO: '4711' linkedForms: - id: f1a2b3 title: Install checklist etaSessionId: eta_k7m2p9x4q8r3 etaUrl: https://eta.page/K7M2-P9X4-Q8R3 ErrorEnvelope: type: object properties: data: type: 'null' error: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/Meta' JobTimeWindow: type: object description: >- Time window on the job's date, local time of the company, as HH:mm strings (24:00 allowed as the end). properties: start: type: string pattern: ^\d{2}:\d{2}$ description: HH:mm. 00:00 when not set. example: '09:00' end: type: string pattern: ^\d{2}:\d{2}$ description: HH:mm. 24:00 when not set. example: '12:00' JobLocation: type: object description: >- Destination coordinates. 0/0 when the job has no location yet (for example while its address is still being geocoded). properties: lat: type: number format: double example: 37.7897 lng: type: number format: double example: -122.4 JobAssignee: type: object description: The assigned member. Empty object when the job is unassigned. properties: id: type: string description: Member id. username: type: string name: type: string email: type: string phone: type: string JobContact: type: object description: On-site contact. Fields that are not set are left out. properties: name: type: string phone: type: string email: type: string JobLinkedForm: type: object properties: id: type: string description: Form template id. title: type: string Error: type: object required: - code - message properties: code: type: string description: Stable error code for programs. enum: - invalid_request - invalid_format - invalid_data - invalid_api_key - unknown_user - authentication_failed - forbidden - not_found - already_exists - throttled - not_ready - clock_invalid - force_logout - internal_error - unknown_error message: type: string description: Why it failed, for people. responses: BadRequest: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: invalid_request message: date must be YYYY-MM-DD meta: path: /jobs method: GET Unauthorized: description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: invalid_api_key message: Invalid Hellotracks API key. meta: path: /jobs method: GET Forbidden: description: The key may not do this. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: forbidden message: No permission. meta: path: /jobs method: GET TooManyRequests: description: Too many requests; slow down. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: throttled message: Too many requests. meta: path: /jobs method: GET ServerError: description: Hellotracks failed; retry later. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: internal_error message: Hellotracks API is temporarily unavailable. meta: path: /jobs method: GET securitySchemes: ApiKey: type: apiKey in: header name: API-Key description: >- Your API key, from More → API & Integrations in the dashboard, or from ht signup / ht auth login. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.