Get a durable agent run

curl --request GET \
  --url https://api.video2ctx.dev/v1/agent/{sessionId}/runs/{runId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.video2ctx.dev/v1/agent/{sessionId}/runs/{runId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.video2ctx.dev/v1/agent/{sessionId}/runs/{runId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userMessageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agentMessageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "conversationTurn": 2,
  "modelStepCount": 1,
  "toolCallCount": 1,
  "status": "pending",
  "route": {
    "route": "topic_research",
    "researchBreadth": "focused",
    "searchQuery": "<string>",
    "useStoryboard": true,
    "answerDetail": "standard"
  },
  "result": {
    "runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "userMessageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agentMessageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "answer": "<string>",
    "intent": "topic_research",
    "confidence": "high",
    "citations": [
      {
        "id": "<string>",
        "sourceId": "<string>",
        "provider": "<string>",
        "excerpt": "<string>",
        "videoId": "<string>",
        "channelId": "<string>",
        "playlistId": "<string>",
        "title": "<string>",
        "url": "<string>",
        "startMs": 1,
        "endMs": 1
      }
    ],
    "artifacts": [
      {
        "type": "<string>",
        "data": {},
        "title": "<string>"
      }
    ],
    "warnings": [
      {
        "code": "<string>",
        "message": "<string>"
      }
    ],
    "billing": {
      "creditsCharged": 1,
      "creditsRemaining": 1
    }
  },
  "error": "<string>",
  "extractionDiagnostics": [
    {
      "version": 1,
      "kind": "storyboard",
      "videoId": "<string>",
      "extractionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attempt": 3,
      "slot": 1,
      "recordedAt": 4503599627370495,
      "elapsedMs": 4503599627370495.5,
      "outcome": "success",
      "capture": "available",
      "events": [
        {
          "stage": "player",
          "profile": "IOS",
          "outcome": "selected",
          "playabilityStatus": "OK",
          "specState": "valid",
          "code": "INVALID_INPUT",
          "inputFormat": "webp",
          "outputFormat": "webp",
          "status": 349,
          "elapsedMs": 4503599627370495.5,
          "timestampMs": 4503599627370495,
          "candidateIndex": 4503599627370495,
          "candidateCount": 4503599627370495,
          "attempt": 4503599627370495,
          "delayMs": 4503599627370495.5,
          "sheetCount": 4503599627370495,
          "width": 4503599627370495,
          "height": 4503599627370495,
          "sourceWidth": 4503599627370495,
          "sourceHeight": 4503599627370495,
          "formatId": 4503599627370495,
          "inputBytes": 4503599627370495,
          "outputBytes": 4503599627370495,
          "exitCode": 0
        }
      ],
      "droppedEvents": 4503599627370495,
      "toolCallId": "<string>",
      "backend": "worker",
      "egress": "direct",
      "status": 349,
      "failureKind": "timeout"
    }
  ],
  "extractionDiagnosticsTruncated": true,
  "transcriptDiagnostics": [
    {
      "version": 1,
      "stage": "transcript_analysis",
      "videoId": "<string>",
      "modelCallId": "<string>",
      "attemptId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attempt": 1,
      "recordedAt": 123,
      "outcome": "started",
      "elapsedMs": 1,
      "code": "GROUNDING_REJECTED",
      "finishReason": "<string>",
      "modelId": "<string>",
      "inputTokens": 1,
      "outputTokens": 1,
      "cancellationReason": "<string>",
      "statusCode": 123,
      "issues": [
        {
          "code": "ENTITY_NOT_SUPPORTED",
          "message": "<string>",
          "findingIndex": 4503599627370495,
          "fieldIndex": 4503599627370495,
          "windowIndex": 4503599627370495
        }
      ],
      "issueCount": 4503599627370495,
      "repairFeedback": "<string>",
      "rejectedOutput": "<string>",
      "sourceContext": {
        "title": "<string>",
        "channel": "<string>"
      },
      "sourceWindows": [
        {
          "index": 0,
          "startMs": 123,
          "endMs": 123,
          "text": "<string>"
        }
      ],
      "captureTruncated": true
    }
  ]
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

GET

agent

{sessionId}

runs

{runId}

Get a durable agent run

curl --request GET \
  --url https://api.video2ctx.dev/v1/agent/{sessionId}/runs/{runId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.video2ctx.dev/v1/agent/{sessionId}/runs/{runId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.video2ctx.dev/v1/agent/{sessionId}/runs/{runId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userMessageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agentMessageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "conversationTurn": 2,
  "modelStepCount": 1,
  "toolCallCount": 1,
  "status": "pending",
  "route": {
    "route": "topic_research",
    "researchBreadth": "focused",
    "searchQuery": "<string>",
    "useStoryboard": true,
    "answerDetail": "standard"
  },
  "result": {
    "runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "userMessageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agentMessageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "answer": "<string>",
    "intent": "topic_research",
    "confidence": "high",
    "citations": [
      {
        "id": "<string>",
        "sourceId": "<string>",
        "provider": "<string>",
        "excerpt": "<string>",
        "videoId": "<string>",
        "channelId": "<string>",
        "playlistId": "<string>",
        "title": "<string>",
        "url": "<string>",
        "startMs": 1,
        "endMs": 1
      }
    ],
    "artifacts": [
      {
        "type": "<string>",
        "data": {},
        "title": "<string>"
      }
    ],
    "warnings": [
      {
        "code": "<string>",
        "message": "<string>"
      }
    ],
    "billing": {
      "creditsCharged": 1,
      "creditsRemaining": 1
    }
  },
  "error": "<string>",
  "extractionDiagnostics": [
    {
      "version": 1,
      "kind": "storyboard",
      "videoId": "<string>",
      "extractionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attempt": 3,
      "slot": 1,
      "recordedAt": 4503599627370495,
      "elapsedMs": 4503599627370495.5,
      "outcome": "success",
      "capture": "available",
      "events": [
        {
          "stage": "player",
          "profile": "IOS",
          "outcome": "selected",
          "playabilityStatus": "OK",
          "specState": "valid",
          "code": "INVALID_INPUT",
          "inputFormat": "webp",
          "outputFormat": "webp",
          "status": 349,
          "elapsedMs": 4503599627370495.5,
          "timestampMs": 4503599627370495,
          "candidateIndex": 4503599627370495,
          "candidateCount": 4503599627370495,
          "attempt": 4503599627370495,
          "delayMs": 4503599627370495.5,
          "sheetCount": 4503599627370495,
          "width": 4503599627370495,
          "height": 4503599627370495,
          "sourceWidth": 4503599627370495,
          "sourceHeight": 4503599627370495,
          "formatId": 4503599627370495,
          "inputBytes": 4503599627370495,
          "outputBytes": 4503599627370495,
          "exitCode": 0
        }
      ],
      "droppedEvents": 4503599627370495,
      "toolCallId": "<string>",
      "backend": "worker",
      "egress": "direct",
      "status": 349,
      "failureKind": "timeout"
    }
  ],
  "extractionDiagnosticsTruncated": true,
  "transcriptDiagnostics": [
    {
      "version": 1,
      "stage": "transcript_analysis",
      "videoId": "<string>",
      "modelCallId": "<string>",
      "attemptId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attempt": 1,
      "recordedAt": 123,
      "outcome": "started",
      "elapsedMs": 1,
      "code": "GROUNDING_REJECTED",
      "finishReason": "<string>",
      "modelId": "<string>",
      "inputTokens": 1,
      "outputTokens": 1,
      "cancellationReason": "<string>",
      "statusCode": 123,
      "issues": [
        {
          "code": "ENTITY_NOT_SUPPORTED",
          "message": "<string>",
          "findingIndex": 4503599627370495,
          "fieldIndex": 4503599627370495,
          "windowIndex": 4503599627370495
        }
      ],
      "issueCount": 4503599627370495,
      "repairFeedback": "<string>",
      "rejectedOutput": "<string>",
      "sourceContext": {
        "title": "<string>",
        "channel": "<string>"
      },
      "sourceWindows": [
        {
          "index": 0,
          "startMs": 123,
          "endMs": 123,
          "text": "<string>"
        }
      ],
      "captureTruncated": true
    }
  ]
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "<string>",
    "details": "<unknown>",
    "requestId": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Permanent personal API key created in the dashboard. Example: curl -H "Authorization: Bearer aty_…" https://your-host/v1/projects

Path Parameters

sessionId

string

required

Session UUID returned by agent admission.

Minimum string length: 1

runId

string

required

Agent run UUID returned by agent admission.

Minimum string length: 1

Query Parameters

responseFormat

enum<string>

default:compact

Compact is the default: answer, deduplicated sources, outcome, and top-level billing. Use legacy explicitly for the previous detailed format. Applies only to this HTTP response. Does not change execution.

Available options:

legacy,

compact

include

string

Optional comma-separated details: artifacts,evidence,diagnostics. Requires responseFormat=compact. Evidence sourceId points to result.sources[].id. Details are omitted unless requested.

Maximum string length: 100

Example:

"evidence,diagnostics"

Response

Current agent run state. Compact results distinguish answered, partial, insufficient_evidence, needs_clarification, and rejected; completed describes execution, not evidence quality or scope acceptance.

Option 1
Option 2

runId

string<uuid>

required

sessionId

string<uuid>

required

userMessageId

string<uuid>

required

Stable identifier assigned to the admitted user message.

agentMessageId

string<uuid>

required

Stable identifier reserved for the agent response.

conversationTurn

integer

required

One-based position of this user and assistant turn within the conversation.

Required range: x >= 1

modelStepCount

integer

required

Completed model steps in the main Agent Core loop. Classifier, transcript analyst, repair, and timeout-finalizer calls are excluded.

Required range: x >= 0

toolCallCount

integer

required

Persisted tool calls for this run, including completed, failed, and finalization calls.

Required range: x >= 0

status

enum<string>

required

Available options:

pending,

running,

completed,

failed,

cancelled

route

object

Option 1
Option 2
Option 3
Option 4

Show child attributes

result

object

Show child attributes

error

string

extractionDiagnostics

object[]

Maximum array length: 64

Show child attributes

extractionDiagnosticsTruncated

boolean

transcriptDiagnostics

object[]

Show child attributes

Start here

Dashboard

Build with Agents

Build with API

API reference

Platform internals

Open source

Get a durable agent run

Authorizations

Path Parameters

Query Parameters

Response