POST /v1/runs

Summary

This endpoint queues and executes a run of a published prompt version. It accepts the identifier of the prompt version, the inputs required by that prompt (text and/or images), and optional runner options. The server attempts to process the run synchronously: if the run finishes within roughly two minutes, it returns the run's outputs and status immediately; otherwise it returns a timeout response with the run ID so you can poll the run using GET /v1/runs/:runId.

HTTP Request

POST /v1/runs

Request Body

The body must be JSON. All fields not listed below are ignored.

Field	Type	Required	Description
promptVersionId	string	Yes	Identifier of the published prompt version to run.
inputs	object	Yes	Container for the inputs expected by the prompt. See the prompt's inputsJTD to learn the required keys and types.
inputs.textInputs	object	Depends on inputsJTD	Record mapping input keys to string values. Only include the keys required by the prompt.
inputs.imageInputs	array of objects	Depends on inputsJTD	Array of image objects. The number of images must exactly match the imageCount specified in the prompt's inputsJTD metadata. Each entry specifies an image using one of two forms: a url object with an image url or a base64 object with a Base64‑encoded image. The discriminator field type determines which form is used.
runOptions	object	No	Partial record whose keys must be one of the supported run options (see Reference: Run options) and whose values are strings. Use this to override default runner settings. Omit to accept all defaults.

Image input objects

Each image entry is a discriminated union on its type:

type	Required fields	Description
"url"	url (string)	A publicly accessible HTTPS URL pointing to the image.
"base64"	base64 (string)	A Base64‑encoded image without any data URL prefix.

Response

Success (200 OK)

When the run finishes within the waiting window, the server 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 success response:

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

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.

Timeout (504 Gateway Timeout)

If the run has not finished within the server's two‑minute polling window, the request returns a timeout response:

{
  "status": "GATEWAY_TIMEOUT_ERROR",
  "message": "The request timed out while waiting for the run to finish.",
  "data": {
    "runId": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

You can continue to monitor the run by calling GET /v1/runs/:runId until it completes.

Error responses

See Error codes.

HTTP status	status code	Description
422	VALIDATION_ERROR	The request body failed validation; for example, the promptVersionId is not a valid UUID, required fields are missing, an image input has an unsupported type, or runOptions contains invalid keys.
404	NOT_FOUND_ERROR	The specified promptVersionId does not correspond to any published prompt version, or the prompt has been unpublished.
504	GATEWAY_TIMEOUT_ERROR	The run did not finish within the allotted time. The data field contains the runId, which can be polled later.

See also

• Retrieve a run: GET /v1/runs/:runId
• Get prompt metadata: GET /v1/prompts/:promptId
• List prompt versions: GET /v1/prompts/:promptId/versions
• Reference: Output item types, Run status, Error codes, Run options