Get a cloud run

Part of Runs, 7 operations. The overview covers keys, scopes and errors.

GET /v1/runs/{run_id}

One run as it stands now.

A caller key holding runs:read (Authorization: Bearer sbc_… or x-api-key: sbc_…), or a signed-in session.

Operation id getRun in Runs.

Path parameters

run_id string required
The run id (a Run id).

Response 200

The run.

application/json: Run.

id string required
object string required
One of run.
status string required
queued, running, then one of done, failed, needs_merge (the work is on branch and waits for a merge) or cancelled. One of queued, running, done, failed, needs_merge, cancelled.
source string required
What started the run. Runs started here are api. One of app, api, cli, routine, slack, linear, jira, github.
project string required
The project the run works on.
prompt string | null required
The prompt, which is also the run’s title: show this to name the run. Null under zero data retention.
mode string required
One of agent, plan, debug.
landing string required
main lands the work on the default branch; pr opens a pull request. One of main, pr.
budget RunBudget required
What the run may spend: wall time, USD and legs.
4 fields
- max_wall_ms integer required
- max_usd number required
- max_legs integer required
- leg_ms integer required
usd_spent number | null required
served_model string | null
The model that served the run, as the runner reported it when the run settled (the same served_model the swarm reports). Null until then, and on a run that settled before this field existed.
served_lane string | null
Who served the run’s model calls (the same served_lane the swarm reports). Every cloud run is platform: Superbot’s own model key, charged in credits to the account. Null on a run that predates this field. One of platform, null.
branch string | null required
The branch the work sits on, when it did not land directly.
landed_commit string | null required
summary string | null required
The runner’s end-of-run diagnostic once it settles, a machine-readable line for debugging and for telling a failed run from a finished one (for example done — sandbox fence-only, 127 tool call(s), local space sp_…), and it can name internal ids. It is not a title and not the run’s answer: name the run by prompt, and do not show this text to end users. Null under zero data retention.
pr_url string | null required
url string | null required
A deep link that opens the run’s project in the Superbot app (superbot://project/<id>), when the project id is linkable.
created_at string required
updated_at string required

Errors

Status	Code	What to change
400	`invalid_request`	A parameter or body field is invalid; `param` names it and `issues` lists every problem.
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`. No key yet: create one at /account/api, or sign a user in at /auth.md.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
429	`rate_limited`	Over the per-key request bucket; retry after `x-ratelimit-reset`.

view .md openapi

Request

curl

curl -sS -X GET "https://superbot.gg/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const runId = 'RUN_ID';
const res = await fetch(`https://superbot.gg/v1/runs/${runId}`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

run_id = "RUN_ID"
res = requests.request(
    "GET",
    f"https://superbot.gg/v1/runs/{run_id}",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The run.

{
  "id": "run_3k9x0q2m1v",
  "object": "run",
  "status": "queued",
  "source": "app",
  "project": "your-project",
  "prompt": "your-prompt",
  "mode": "agent",
  "landing": "main",
  "budget": {
    "max_wall_ms": 0,
    "max_usd": 0,
    "max_legs": 0,
    "leg_ms": 0
  },
  "usd_spent": 0,
  "served_model": "your-served-model",
  "served_lane": "platform",
  "branch": "your-branch",
  "landed_commit": "your-landed-commit",
  "summary": "your-summary",
  "pr_url": "https://example.com",
  "url": "https://example.com",
  "created_at": "your-created-at",
  "updated_at": "your-updated-at"
}

400 The request is malformed or a parameter is invalid; `param` names the field.

{
  "error": "invalid_request",
  "message": "A parameter or body field is invalid; param names it and issues lists every problem.",
  "doc_url": "https://superbot.gg/developers#errors-invalid_request",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

401 The bearer is missing, malformed or unknown.

{
  "error": "unauthorized",
  "message": "Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.",
  "doc_url": "https://superbot.gg/developers#errors-unauthorized",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

403 The key lacks a scope (insufficient_scope), is revoked, or may not call this route.

{
  "error": "insufficient_scope",
  "message": "The key lacks the scope in required_scopes; mint a key that holds it.",
  "doc_url": "https://superbot.gg/developers#errors-insufficient_scope",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

429 Over the per-key request bucket; retry after x-ratelimit-reset.

{
  "error": "rate_limited",
  "message": "Over the per-key request bucket; retry after x-ratelimit-reset.",
  "doc_url": "https://superbot.gg/developers#errors-rate_limited",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}