> ## Documentation Index > Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt > Use this file to discover all available pages before exploring further. # List coming runs > The coming runs of your automations between `from` and `to`, at most 62 days apart, as a calendar shows them: each with its `run_at`, its state (`pending`, `queued` or `skipped`) and its `version`. Pass `automation_id` for one automation's. Runs further ahead are worked out from the schedule (`projected: true`): you can move one (with `occurrence_version: 0`), and skip it once it comes closer. Past runs are in [List runs](/automations/api/list-runs). Needs the `automations:read` scope. ## OpenAPI ````yaml automations/api/openapi.json GET /v1/automations/occurrences openapi: 3.1.0 info: title: Vortex IQ Automations API version: 1.0.0 description: > REST API for Vortex IQ Automations. List the templates your organisation can use, set automations up on your stores, schedule them, run them, and follow every run, from your own tools instead of the Automations screens. The API is served from `https://automations-api.vortexiq.ai`; the login that gives you a token is on `https://app.vortexiq.ai`. Every call acts as the person who logged in, within their organisation, and every answer is JSON. See [Authentication](/automations/api/authentication). contact: name: Vortex IQ Support url: https://www.vortexiq.ai/contact-us servers: - url: https://automations-api.vortexiq.ai description: Vortex IQ Automations (production) security: - bearerAuth: [] - apiCredential: [] tags: - name: Authentication description: >- Exchange your identity and your organisation's API credential for a bearer token. - name: Templates & stores description: What you can set up, and what it can run on. - name: Automations description: Set automations up, read them and change them. - name: Automation controls description: Pause, resume, archive and restore. - name: Runs description: Run an automation now, follow a run, read the history. - name: Schedules & calendar description: Preview a schedule, list the coming runs, move or skip one. - name: Approvals description: >- The runs waiting for a decision. Deciding happens in the Vortex IQ app only. - name: Imported workflows description: >- Bring an n8n or Shopify Flow workflow in, see how it would run, and run it as your own automation. - name: Status description: >- Whether Automations are on for your organisation, and how the service is doing. paths: /v1/automations/occurrences: get: tags: - Schedules & calendar summary: List coming runs description: >- The coming runs of your automations between `from` and `to`, at most 62 days apart, as a calendar shows them: each with its `run_at`, its state (`pending`, `queued` or `skipped`) and its `version`. Pass `automation_id` for one automation's. Runs further ahead are worked out from the schedule (`projected: true`): you can move one (with `occurrence_version: 0`), and skip it once it comes closer. Past runs are in [List runs](/automations/api/list-runs). Needs the `automations:read` scope. operationId: listOccurrences parameters: - name: from in: query required: true description: The start of the period (ISO 8601). schema: $ref: '#/components/schemas/Timestamp' - name: to in: query required: true description: The end of the period (ISO 8601), at most 62 days after `from`. schema: $ref: '#/components/schemas/Timestamp' - name: automation_id in: query required: false schema: $ref: '#/components/schemas/Id' description: Only this automation's coming runs. responses: '200': description: The coming runs in the period, by the time they will really run. content: application/json: schema: type: object required: - success - data - contract_version properties: success: type: boolean const: true contract_version: $ref: '#/components/schemas/ContractVersion' data: type: object required: - occurrences properties: occurrences: type: array items: $ref: '#/components/schemas/Occurrence' example: success: true contract_version: 1 data: occurrences: - automation_id: 01M51XBN46TASJ8NG9MA26GVKJ automation_name: Low-stock and sold-out watch ยท Shopify automation_version: 1 timezone: Europe/London slot_at: '2026-10-19T06:00:00.000Z' run_at: '2026-10-19T06:00:00.000Z' state: pending reason: null run_id: null run_status: null moved_from: null version: 1 projected: false - automation_id: 01M520GSDQH5TQ3CAAQ584TTKH automation_name: Weekly catalogue check automation_version: 2 timezone: Europe/London slot_at: '2026-10-19T06:00:00.000Z' run_at: '2026-10-19T06:02:00.000Z' state: pending reason: null run_id: null run_status: null moved_from: null version: 1 projected: false '401': $ref: '#/components/responses/Unauthorised' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/TooManyRequests' security: - bearerAuth: - automations:read - apiCredential: - automations:read components: schemas: Timestamp: type: string format: date-time description: A time in UTC (ISO 8601). Id: type: string description: A public id (a ULID). pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ ContractVersion: type: integer minimum: 1 description: >- The version of the API this answer follows. It changes only for a breaking change. Occurrence: type: object description: >- One coming run. `slot_at` is the time the schedule produced and never changes; `run_at` is when it will really run. required: - automation_id - automation_name - automation_version - timezone - slot_at - run_at - state - reason - run_id - run_status - moved_from - version - projected properties: automation_id: $ref: '#/components/schemas/Id' automation_name: type: string automation_version: type: integer minimum: 1 description: >- The automation's `version` when this was read, which a move sends back. timezone: type: string description: The automation's IANA zone, to show the times in. slot_at: $ref: '#/components/schemas/Timestamp' run_at: $ref: '#/components/schemas/Timestamp' state: $ref: '#/components/schemas/OccurrenceState' reason: oneOf: - $ref: '#/components/schemas/OccurrenceReason' - type: 'null' run_id: oneOf: - $ref: '#/components/schemas/Id' - type: 'null' run_status: oneOf: - $ref: '#/components/schemas/RunStatus' - type: 'null' description: >- The run's status once the slot was queued, so a past block can say what happened; null before. moved_from: oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' description: Where the run was before a person moved it; null when never moved. version: type: integer minimum: 0 description: Raised by every edit; 0 for a projected row. projected: type: boolean description: >- Worked out from the schedule further ahead. A move writes it first (send `occurrence_version: 0`); it cannot be skipped until it comes closer. OccurrenceState: type: string enum: - pending - queued - skipped OccurrenceReason: type: string enum: - skipped_previous_running - skipped_waiting_approval - skipped_too_late - by_merchant RunStatus: type: string enum: - queued - running - waiting_approval - succeeded - failed - refused - cancelled - expired ErrorResponse: type: object required: - success - message - contract_version properties: success: type: boolean const: false contract_version: $ref: '#/components/schemas/ContractVersion' message: type: string description: Plain words saying what happened and what to do. code: type: string description: >- A stable code to act on, such as `wrong_state`, `stale_version` or `allowance_spent`. errors: type: object description: Field name to messages, for 422. additionalProperties: type: array items: type: string responses: Unauthorised: description: >- The token is missing, has expired, or is no longer valid (for example, the API credential was rotated or disabled). The answer carries `WWW-Authenticate`; log in again for a new token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- Your token is valid but may not do this: it lacks the scope, the operation is not part of the Automations API, or Automations are switched off for your organisation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationFailed: description: The request was not valid; `errors` names the fields. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' TooManyRequests: description: >- Too many calls in a minute from you or your organisation; nothing was done. `Retry-After` says how many seconds to wait. headers: Retry-After: schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- A bearer token from [Login](/automations/api/login), sent as `Authorization: Bearer `. Valid for 60 minutes; it acts as the person named at login, within their organisation, and never approves. Rotating or disabling the organisation's API credential ends every token made with it on its next call. See [Authentication](/automations/api/authentication). apiCredential: type: oauth2 description: >- Your organisation's API credential, exchanged at [Login](/automations/api/login) for the bearer token above: an OAuth 2.0 client-credentials request, with the `username`, `email` and `organization_name` of the person the token acts as sent as extra fields, as Postman's OAuth 2.0 helper can send them. The token never holds `automations:approve`. flows: clientCredentials: tokenUrl: https://app.vortexiq.ai/v2/api/automations/login scopes: automations:read: >- Read automations, templates, stores, runs, the calendar, approvals and imports. automations:write: >- Set automations up, change, pause, resume, archive, restore and run them; move and skip coming runs; keep and delete imports. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.