GET /v1/runs/:runId

Summary

Retrieve the current status and outputs of a previously created run using its runId. Use this to poll for completion after creating a run, or to fetch the final outputs later.

HTTP Request

GET /v1/runs/:runId

Path parameters

Parameter	Type	Required	Description
runId	string	Yes	Identifier of the run.

Response

Success (200 OK)

Returns a JSON object whose status is "SUCCESS" and a data object containing:

Field	Type	Description
runId	string	Identifier of the run.
outputs	array of objects	List of output items. Each item has a type field ("text", "image", or "error") and a data field containing the corresponding content. See Output item types.
runStatus	string	Status of the run. Possible values include "queued", "running", "succeeded", and "failed". See Run status.
tokens	integer	BetterPrompt tokens consumed. See account page for token details.

An example succeeded run:

{
  "status": "SUCCESS",
  "data": {
    "runId": "01234567-89ab-cdef-0123-456789abcdef",
    "outputs": [{ "type": "text", "data": "A witty caption for your image…" }],
    "runStatus": "succeeded",
    "tokens": 132
  }
}

An example in-progress run:

{
  "status": "SUCCESS",
  "data": {
    "runId": "01234567-89ab-cdef-0123-456789abcdef",
    "outputs": [],
    "runStatus": "running",
    "tokens": 0
  }
}

Output item types

type	Shape	Description
text	{ "type": "text", "data": string }	Generated text content.
image	{ "type": "image", "data": string }	The URL to a generated image resource. The URL is publicly accessible and expires after 24 hours.
error	{ "type": "error", "data": string }	Error message when a step fails during generation.

Error responses

See Error Handling.

HTTP status	status code	Description
404	NOT_FOUND_ERROR	The specified runId does not exist or you do not have access to this run.

See also

• Create a run: POST /v1/runs
• Reference: Output item types, Run status, Error Handling