Runs

What is a run?

A run is a single execution of a prompt version with a set of inputs. When you create a run, BetterPrompt queues it, sends the inputs to the AI model, and returns the generated outputs. Each run has a unique runId and consumes credits.

Lifecycle

Every run moves through these statuses:

Status	Meaning
queued	The run is waiting to be processed.
running	The model is generating output.
succeeded	Generation finished — outputs are ready.
failed	Something went wrong during generation.

Synchronous response with timeout

When you create a run, the API tries to return the result synchronously. If the model finishes within roughly two minutes, you get the outputs in the response immediately:

{
  "status": "SUCCESS",
  "data": {
    "runId": "...",
    "outputs": [{ "type": "text", "data": "Generated content…" }],
    "runStatus": "succeeded",
    "tokens": 132
  }
}

If it takes longer (common with video or complex image generation), the API returns a 504 timeout with the runId:

{
  "status": "GATEWAY_TIMEOUT_ERROR",
  "message": "The request timed out while waiting for the run to finish.",
  "data": { "runId": "..." }
}

Polling for results

After a timeout, poll the run until it completes:

curl "https://api.betterprompt.me/v1/runs/<RUN_ID>" \
  -H "Authorization: Bearer $BETTERPROMPT_API_KEY"

Check runStatus in the response — keep polling while it is queued or running. Once it is succeeded or failed, the run is finished.

Output types

A run produces an array of output items. Each item has a type and data field:

Type	Description
text	Generated text content.
image	URL to a generated image. Expires after 24 hours.
video	URL to a generated video. Expires after 24 hours.
error	An error message if a generation step failed.

A single run can produce multiple items — for example, a text caption followed by an image.

Inputs

The inputs you send must match the prompt's expected input fields:

• textInputs — an object mapping field names to string values.
• imageInputs — an array of image objects, each with type: "url" or type: "base64".

You can also override the model and tweak execution with runModel and runOptions. See Models & Options and Run options.

API reference

• POST /v1/runs — Create a run
• GET /v1/runs/:runId — Retrieve a run
• GET /v1/runs — List runs