Skip to main content

Get run status

GET /projects/:projectid/workflows/:workflowid/run/:invocationId

Retrieves the current state of a run created by Queue a workflow run. Once execution has completed, the response includes its result.

Authentication and permissions​

Send the complete project key in Authorization, without Bearer. The key needs workflows.read on the workflow. Run permission alone is not sufficient.

The invocation must belong to both the project and workflow in the URL.

Request​

All three path parameters are required:

ParameterValue
projectidThe project ID used when starting the run.
workflowidThe workflow ID used when starting the run.
invocationIdThe ID returned by the queue endpoint.

There is no request body. Using the Quickstart variables:

export INTELLECTIBLE_WORKFLOW_ID="YOUR_WORKFLOW_ID"
export INTELLECTIBLE_INVOCATION_ID="YOUR_INVOCATION_ID"

curl --include --request GET \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/workflows/${INTELLECTIBLE_WORKFLOW_ID}/run/${INTELLECTIBLE_INVOCATION_ID}"

Response while running​

200 OK means the status lookup succeeded:

{
"success": true,
"invocationId": "example-invocation-id",
"projectId": "example-project-id",
"workflowId": "example-workflow-id",
"state": "active",
"statusCode": 200
}
StateMeaning and next step
waitingQueued for execution. Poll again later.
activeExecution is in progress. Poll again later.
delayedWaiting for a scheduled queue delay. Poll again later.
completedExecution returned a result. Inspect output.success.
failedQueued execution failed. Inspect failedReason.
unknown or another stateNo confirmed final outcome. Do not assume success or immediately submit another run; use a bounded polling deadline and investigate if it persists.

Completed result​

A successful greeting workflow could return:

{
"success": true,
"invocationId": "example-invocation-id",
"projectId": "example-project-id",
"workflowId": "example-workflow-id",
"state": "completed",
"statusCode": 200,
"output": {
"success": true,
"statusCode": 200,
"result": {
"outputs": {
"greeting": "Hello Ada"
}
}
}
}

The top-level success describes the lookup. The nested output.success describes the workflow outcome. A completed invocation can contain output.success: false with error details instead of successful outputs.

Named workflow outputs are under output.result.outputs. Their structure depends on the workflow.

Failed execution​

When the queue reports state: "failed", the response includes failedReason rather than a completed output. The HTTP status and top-level success may still indicate a successful status lookup.

Treat both state: "failed" and a completed result with output.success: false as failures. Check Logs → API for execution details; do not assume earlier workflow actions were rolled back.

Errors and retention​

  • 401: missing or invalid project credential.
  • 403: no read permission on the workflow.
  • 404: the invocation is unavailable or does not belong to the project/workflow in the URL.
  • 429: a request-rate limit was reached.

Completed results are retained only briefly and can be removed as more runs finish. Poll during execution, collect the result promptly, and persist important outputs. A 404 after a delay can mean the status has expired; it does not prove that the run never happened.

Use a measured polling interval with backoff and an overall deadline. Stop on completion or failure. See Errors, limits and retries.