Skip to content
Try for free
On this page

Tables

Get run dispatch

Get a dispatch's current state. Poll until `complete` or `canceled`; use row reads with `includeRunState` for per-cell outcomes. OAuth scope: `api:read`.

GET/api/v2/tables/{tableId}/dispatches/{dispatchId}

Get a dispatch's current state. Poll until complete or canceled; use row reads with includeRunState for per-cell outcomes.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Path parameters

tableIdstringRequired

Unique table identifier.

minLength
1
dispatchIdstringRequired

Unique table run-dispatch identifier.

minLength
1

Query parameters

workspaceIdstringRequired

Workspace that owns the transfer resource.

minLength
1
maxLength
128

Responses

200

The requested run dispatch.

object

A single table run dispatch.

1 field
dataobjectRequired

Response data.

12 fields
idstringRequired

Unique dispatch identifier.

tableIdstringRequired

Table the dispatch runs against.

workspaceIdstringRequired

Workspace that owns the dispatch.

statusstringRequired

Current dispatch lifecycle state.

enum
["pending","dispatching","complete","canceled"]
modestringRequired

Which cells the dispatch targets: all re-runs settled cells, incomplete skips them, new covers only cells that have never run.

enum
["all","incomplete","new"]
scopeobjectRequired

What the dispatch was asked to run.

4 fields
groupIdsarrayRequired

Workflow groups the dispatch runs.

Schema details
Array itemstring
rowIdsarray

Explicit rows the dispatch targets. Absent means it was given no row list and walks every eligible row, narrowed by filtered and excludeRowIds when either is present.

Schema details
Array itemstring
filteredboolean

Present and true when a stored filter narrows which rows run. The filter itself is not published: it is held compiled, in a different grammar from the predicate the request was written in. Absent means no filter narrows the dispatch — which, with no rowIds and no excludeRowIds, is what means every eligible row.

excludeRowIdsarray

Rows the walk skips. Independent of filtered: a dispatch may exclude rows from a filtered set or from every eligible row. Never present alongside rowIds, which the run rejects and the walk would ignore.

Schema details
Array itemstring

Additional properties are not allowed.

limitvalueRequired

Cap on how much work the dispatch does, or null when unbounded.

Schema details

Any of

Option 1object
2 fields
typestringRequired

Unit the cap counts.

const
rows
maxintegerRequired

Hard ceiling in units of type.

maximum
9007199254740991
exclusiveMinimum
0

Additional properties are not allowed.

Option 2null
processedCountintegerRequired

Units of limit.type consumed so far.

minimum
0
maximum
9007199254740991
isManualRunbooleanRequired

True when a caller started the run, false for an automatic re-fire.

requestedAtstringRequired

ISO 8601 timestamp when the dispatch was created.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
completedAtvalueRequired

ISO 8601 timestamp when the dispatch completed, or null.

Schema details

Any of

Option 1string
format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Option 2null
canceledAtvalueRequired

ISO 8601 timestamp when the dispatch was canceled, or null.

Schema details

Any of

Option 1string
format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Option 2null

Additional properties are not allowed.

Additional properties are not allowed.

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit