Agent Run Status

GEThttps://agent.blackbox.ai/api/v1/agent/status

Check the current status of a Claude Agent run by runId. Checks live in-memory state first, falls back to the database.

This endpoint returns the raw internal status of an agent run identified by runId. Unlike the task status endpoint, this returns the internal status values directly (not mapped to external values) and also includes the assistantMessageId.

Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:

Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
Once provisioning completes, you will be redirected to your Dashboard
From the Dashboard, create an API key to use with all Agent API requests

Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

Headers

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Query Parameters

runIdstringrequired

The unique run identifier returned when the task was created.

Example: runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response Fields

runIdstring | null

The run identifier. null if not found.

statusstring | null

Internal status of the run.

Possible values: queued, running, completed, failed, cancelled, interrupted, or null if not found.

assistantMessageIdstring | null

ID of the assistant message being generated. null if not yet assigned or not found.

errorstring | null

Error message if the run failed, null otherwise.

Request Example

curl 'https://agent.blackbox.ai/api/v1/agent/status?runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

const response = await fetch(
  `https://agent.blackbox.ai/api/v1/agent/status?runId=${RUN_ID}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

const data = await response.json();
console.log(`Status: ${data.status}`);
console.log(`Message ID: ${data.assistantMessageId}`);

import requests

API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.get(
    "https://agent.blackbox.ai/api/v1/agent/status",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"runId": RUN_ID},
)
data = response.json()
print(f"Status: {data['status']}")
print(f"Message ID: {data['assistantMessageId']}")

Response Example

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "assistantMessageId": "msg_abc123xyz456",
  "error": null
}

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "assistantMessageId": "msg_abc123xyz456",
  "error": null
}

{
  "runId": null,
  "status": null,
  "assistantMessageId": null,
  "error": null
}

{
  "error": "runId query parameter is required"
}

Error Codes

Status Code	Error	Description
200	Success	Status returned (may be null if run not found)
400	Bad Request	Missing `runId` query parameter
401	Unauthorized	Invalid or missing API key