GET
/
v1
/
teams
/
{teamId}
/
agents
/
{agentId}
/
runs
/
{runId}
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.agents.getAgentRun({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  agentId: process.env.OCTOSPARK_AGENT_ID ?? "agentId",
  runId: process.env.OCTOSPARK_RUN_ID ?? "runId",
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scheduleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workflowScheduleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "firingId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "decisionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "prompt": "<string>",
  "overrides": {
    "timeLimitSeconds": 10800,
    "strategy": "<string>"
  },
  "chatSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "chatId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "langfuseTraceId": "<string>",
  "langfuseTraceUrl": "<string>",
  "costDecimillicents": 123,
  "error": "<string>",
  "result": {},
  "startedAt": "<string>",
  "finishedAt": "<string>",
  "createdAt": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

​
agentId
string
required

Managed agent id (UUID), as returned by the list/create agents endpoints.

​
runId
string
required

Agent run id (UUID), as returned by the start/list runs endpoints.

Response

AgentRun

​
id
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
teamId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
agentId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
agentVersionId
string<uuid>
required

The immutable version this run pinned before it started.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
trigger
enum<string>
required

What started the run: manual (UI), schedule (sweeper), or api (POST runs).

Available options:
manual,
schedule,
api,
chat,
slideshow,
dream
​
scheduleId
string<uuid> | null
required

The schedule that fired this run, when any.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
workflowScheduleId
string<uuid> | null
required

The workflow schedule that owns this run: the schedule that fired it, or the agent's manual runs schedule for direct, API and review-queue runs. Null only for runs created before workflow schedules existed.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
firingId
string<uuid> | null
required

The workflow schedule firing that started this run; null for runs not started by a firing.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
campaignId
string<uuid> | null
required

The campaign the run is attributed to (from its workflow schedule); null for none.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
decisionId
string<uuid> | null
required

The optimiser decision that picked this run's agent version (optimised selection); null otherwise.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
prompt
string | null
required

The user-message prompt the run started from.

​
overrides
object
required

Per-run overrides applied on top of the version.

​
status
enum<string>
required

queued until the loop starts, running while it drains, then succeeded, failed or cancelled.

Available options:
queued,
running,
paused,
succeeded,
failed,
cancelled
​
chatSessionId
string<uuid> | null
required

The chat session hosting the run's transcript and drafts.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
chatId
string<uuid> | null
required

The client session id of that chat, usable as the inbox deep link (?chatid=); null when the session is gone.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
langfuseTraceId
string | null
required

The Langfuse trace id of the run, when tracing was active.

​
langfuseTraceUrl
string | null
required

A link to the run's trace in the Langfuse UI; null when the run has no trace or the deployment has no Langfuse project to link to.

​
costDecimillicents
integer
required

Credits the run settled, in decimillicents.

​
error
string | null
required

Why the run failed or stopped, when it did.

​
result
object
required

The structured result the run reported, matching its output contract (or the platform default run report). When resultValidation is invalid this is { raw: string } holding the final text. Null until the run finishes and for free-text runs.

​
resultValidation
enum<string> | null
required

valid: result matches the contract. invalid: it did not match after one repair attempt; the run still succeeded and result.raw holds the text. text: the run had no contract. Null until the run finishes.

Available options:
valid,
invalid,
text
​
startedAt
string | null
required

When the loop started (ISO-8601 UTC).

​
finishedAt
string | null
required

When the run reached a terminal status (ISO-8601 UTC).

​
createdAt
string
required

When the run row was created (ISO-8601 UTC).