GET /v1/runs

Summary

List runs created by the authenticated user. Results are ordered by creation time (newest first) and use cursor-based pagination. You can filter by status and date range.

HTTP Request

GET /v1/runs?limit=10&status=succeeded&since=1700000000&until=1710000000

Query parameters

Parameter	Type	Required	Default	Description
limit	integer	No	10	Number of runs to return. Min 1, max 50.
startingAfter	string	No	—	Cursor for forward pagination. Returns runs created before this run ID.
endingBefore	string	No	—	Cursor for backward pagination. Returns runs created after this run ID.
status	string	No	—	Filter by run status: queued, running, succeeded, or failed.
since	integer	No	—	Unix timestamp. Only return runs created at or after this time.
until	integer	No	—	Unix timestamp. Only return runs created before this time.

WARNING

You cannot use startingAfter and endingBefore in the same request. If since is provided, it must be less than until.

Response

Success (200 OK)

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

Field	Type	Description
rows	array of objects	List of runs.
rows[].runId	string	Identifier of the run.
rows[].promptVersionId	string	Identifier of the prompt version used.
rows[].outputs	array of objects	Output items. See Output item types.
rows[].runStatus	string	Status of the run. See Run status.
rows[].credits	integer | null	Credits consumed. null if the run was free.
rows[].runName	string	Display name of the run.
rows[].createdAt	string (ISO 8601)	When the run was created.
hasMore	boolean	true if more results are available beyond this page.

Example response

{
  "status": "SUCCESS",
  "data": {
    "rows": [
      {
        "runId": "01234567-89ab-cdef-0123-456789abcdef",
        "promptVersionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "outputs": [{ "type": "text", "data": "Generated blog post content…" }],
        "runStatus": "succeeded",
        "credits": 150,
        "runName": "Blog post writer",
        "createdAt": "2025-11-03T10:15:30.000Z"
      }
    ],
    "hasMore": false
  }
}

Pagination

Use cursor-based pagination to iterate through results:

# First page
curl "https://api.betterprompt.me/v1/runs?limit=10" \
  -H "Authorization: Bearer $BETTERPROMPT_API_KEY"

# Next page — use the last runId from the previous response
curl "https://api.betterprompt.me/v1/runs?limit=10&startingAfter=<LAST_RUN_ID>" \
  -H "Authorization: Bearer $BETTERPROMPT_API_KEY"

Continue paginating until hasMore is false.

Error responses

HTTP status	status code	Description
422	VALIDATION_ERROR	Invalid parameters (e.g. both cursors, invalid UUID).

See also

• Create a run: POST /v1/runs
• Retrieve a run: GET /v1/runs/:runId
• Reference: Output item types, Run status