> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracks.alpic.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a run > Returns a run and its current status. ## OpenAPI ````yaml https://tracks.alpic.ai/api/openapi.json get /runs/{id} openapi: 3.1.0 info: title: Tracks API version: 0.0.1 description: >- Run coding agents such as Claude Code in isolated sandboxes with an API key of your organization. Create a run with a prompt, then follow its output and what it costs, or launch an experiment to compare agents on your scenarios. servers: - url: https://tracks.alpic.ai/api security: [] tags: - name: Runs description: Start coding agents and follow their work. - name: Files description: Upload files to place in a run's sandbox. - name: Connections description: >- Let agents use MCP servers as one of their users, without their credentials entering the sandbox. - name: Experiments description: >- Define scenarios to give several agents in several variants, judged on what they did. - name: Executions description: Launch experiments and read their results. - name: Library description: What your experiments can give their agents. - name: System paths: /runs/{id}: get: tags: - Runs summary: Get a run description: Returns a run and its current status. operationId: runs.get parameters: - name: id in: path schema: $ref: '#/components/schemas/RunId' required: true responses: '200': description: A coding agent working on your prompt in an isolated sandbox. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ActiveRun' - $ref: '#/components/schemas/EndedRun' - $ref: '#/components/schemas/FailedRun' description: A coding agent working on your prompt in an isolated sandbox. '400': description: >- The request is invalid: a value is missing, has the wrong type or is out of range. Fix it before sending the request again. content: application/json: schema: $ref: '#/components/schemas/InvalidRequestEncoded' '401': description: >- The API key is missing, malformed or revoked, or its organization is closed. content: application/json: schema: $ref: '#/components/schemas/ApiKeyRefusedEncoded' '404': description: No run with this id exists in your organization. content: application/json: schema: $ref: '#/components/schemas/RunNotFoundEncoded' security: - bearer: [] components: schemas: RunId: type: string description: Unique identifier of the run. ActiveRun: type: object properties: id: $ref: '#/components/schemas/RunId' input_files: type: array items: type: object properties: id: type: string description: Reference returned when requesting a file upload. name: type: string description: >- Filename, without directories; up to 128 ASCII letters, digits, spaces, dots, hyphens or underscores, starting with a letter or digit. content_type: type: string description: >- MIME type, without parameters; `application/octet-stream` when unknown. size: type: integer minimum: 1 maximum: 20971520 description: Exact size in bytes, from 1 to 20 MiB. path: type: string description: Absolute path in the agent's sandbox. download_url: type: string description: Signed download URL, valid for 15 minutes. download_expires_at: type: string required: - id - name - content_type - size - path - download_url - download_expires_at additionalProperties: false labels: type: object additionalProperties: type: string maxLength: 256 description: >- Labels you attach to the run to find it again, as keys and values, such as `{ "ticket": "ENG-42" }`. We never read them. Keys match `^[A-Za-z0-9_.-]{1,64}$`; at most 20 labels with values of up to 256 characters. maxProperties: 20 agent: $ref: '#/components/schemas/Agent' environment: $ref: '#/components/schemas/Environment' budget_usd: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN one_shot: type: boolean description: Whether the run ends as soon as its first prompt finishes. idle_timeout_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- How long the run waits for a follow-up prompt before it ends, in seconds. Absent for a one-shot run. time_limit_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Longest the run may last, in seconds from when it starts. started_at: type: string last_prompt: anyOf: - $ref: '#/components/schemas/UnfinishedPrompt' - $ref: '#/components/schemas/FinishedPrompt' description: One instruction to the agent and the work it did in response. status: type: string enum: - preparing - working - idle description: >- `preparing` while its sandbox gets ready, `working` while the agent works on a prompt, `idle` while it waits for a follow-up prompt. required: - id - input_files - labels - agent - environment - budget_usd - one_shot - time_limit_seconds - started_at - last_prompt - status additionalProperties: false description: A run that has not ended. EndedRun: type: object properties: id: $ref: '#/components/schemas/RunId' input_files: type: array items: type: object properties: id: type: string description: Reference returned when requesting a file upload. name: type: string description: >- Filename, without directories; up to 128 ASCII letters, digits, spaces, dots, hyphens or underscores, starting with a letter or digit. content_type: type: string description: >- MIME type, without parameters; `application/octet-stream` when unknown. size: type: integer minimum: 1 maximum: 20971520 description: Exact size in bytes, from 1 to 20 MiB. path: type: string description: Absolute path in the agent's sandbox. download_url: type: string description: Signed download URL, valid for 15 minutes. download_expires_at: type: string required: - id - name - content_type - size - path - download_url - download_expires_at additionalProperties: false labels: type: object additionalProperties: type: string maxLength: 256 description: >- Labels you attach to the run to find it again, as keys and values, such as `{ "ticket": "ENG-42" }`. We never read them. Keys match `^[A-Za-z0-9_.-]{1,64}$`; at most 20 labels with values of up to 256 characters. maxProperties: 20 agent: $ref: '#/components/schemas/Agent' environment: $ref: '#/components/schemas/Environment' budget_usd: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN one_shot: type: boolean description: Whether the run ends as soon as its first prompt finishes. idle_timeout_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- How long the run waits for a follow-up prompt before it ends, in seconds. Absent for a one-shot run. time_limit_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Longest the run may last, in seconds from when it starts. started_at: type: string last_prompt: anyOf: - $ref: '#/components/schemas/UnfinishedPrompt' - $ref: '#/components/schemas/FinishedPrompt' description: One instruction to the agent and the work it did in response. status: type: string enum: - ended ended_at: type: string end_reason: type: string enum: - completed - idle_timeout - time_limit - budget_exceeded - canceled required: - id - input_files - labels - agent - environment - budget_usd - one_shot - time_limit_seconds - started_at - last_prompt - status - ended_at - end_reason additionalProperties: false description: A run that ended without failing. FailedRun: type: object properties: id: $ref: '#/components/schemas/RunId' input_files: type: array items: type: object properties: id: type: string description: Reference returned when requesting a file upload. name: type: string description: >- Filename, without directories; up to 128 ASCII letters, digits, spaces, dots, hyphens or underscores, starting with a letter or digit. content_type: type: string description: >- MIME type, without parameters; `application/octet-stream` when unknown. size: type: integer minimum: 1 maximum: 20971520 description: Exact size in bytes, from 1 to 20 MiB. path: type: string description: Absolute path in the agent's sandbox. download_url: type: string description: Signed download URL, valid for 15 minutes. download_expires_at: type: string required: - id - name - content_type - size - path - download_url - download_expires_at additionalProperties: false labels: type: object additionalProperties: type: string maxLength: 256 description: >- Labels you attach to the run to find it again, as keys and values, such as `{ "ticket": "ENG-42" }`. We never read them. Keys match `^[A-Za-z0-9_.-]{1,64}$`; at most 20 labels with values of up to 256 characters. maxProperties: 20 agent: $ref: '#/components/schemas/Agent' environment: $ref: '#/components/schemas/Environment' budget_usd: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN one_shot: type: boolean description: Whether the run ends as soon as its first prompt finishes. idle_timeout_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- How long the run waits for a follow-up prompt before it ends, in seconds. Absent for a one-shot run. time_limit_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Longest the run may last, in seconds from when it starts. started_at: type: string last_prompt: anyOf: - $ref: '#/components/schemas/UnfinishedPrompt' - $ref: '#/components/schemas/FinishedPrompt' description: One instruction to the agent and the work it did in response. status: type: string enum: - ended ended_at: type: string end_reason: type: string enum: - failed failure: type: string description: What went wrong. failure_kind: $ref: '#/components/schemas/FailureKind' required: - id - input_files - labels - agent - environment - budget_usd - one_shot - time_limit_seconds - started_at - last_prompt - status - ended_at - end_reason - failure - failure_kind additionalProperties: false description: A run that ended because something went wrong. InvalidRequestEncoded: type: object properties: _tag: type: string enum: - InvalidRequest message: type: string description: Every problem found, in one sentence. location: type: string enum: - path - query - header - body description: The part of the request that is wrong. issues: type: array items: $ref: '#/components/schemas/RequestIssue' description: Each problem found, with where it is. required: - _tag - message - location - issues additionalProperties: false ApiKeyRefusedEncoded: type: object properties: _tag: type: string enum: - ApiKeyRefused message: type: string required: - _tag - message additionalProperties: false RunNotFoundEncoded: type: object properties: _tag: type: string enum: - RunNotFound message: type: string required: - _tag - message additionalProperties: false Agent: type: object properties: harness: $ref: '#/components/schemas/Harness' model: type: string minLength: 1 description: >- Model the agent uses, such as `claude-sonnet-5-5`, or a Cursor model id such as `gpt-5.6-luna-low`. required: - harness - model additionalProperties: false description: The coding agent and the model it uses. Environment: type: object properties: repository: type: string minLength: 1 description: URL of a Git repository to clone before the agent starts. variables: type: array items: type: string description: >- Names of the environment variables set in every process of the agent. Their values are never returned. setup: type: string minLength: 1 maxLength: 32768 description: >- Shell script run with bash in the repository directory after checkout and before the first prompt, with the run's variables set, while the run is `preparing`. A non-zero exit fails the run. It may run again after a restart on our side: make it idempotent. At most 32768 characters. teardown: type: string minLength: 1 maxLength: 32768 description: >- Shell script run with bash in the repository directory after the run ends and before its sandbox is destroyed, with the run's variables set. Its exit code doesn't change how the run ended. It may run again after a restart on our side: make it idempotent. At most 32768 characters. skills: type: array items: $ref: '#/components/schemas/Skill' mcp_servers: type: array items: $ref: '#/components/schemas/McpServer' browser: type: boolean description: Whether the agent was given a headless Chromium in its sandbox. required: - variables - skills - mcp_servers - browser additionalProperties: false description: What the agent works on. UnfinishedPrompt: type: object properties: run_id: $ref: '#/components/schemas/RunId' index: type: integer minimum: 1 maximum: 9007199254740991 description: Position of the prompt in its run, starting at 1. text: type: string description: What you asked the agent to do. model: type: string description: Model for this prompt, when not the run's. submitted_at: type: string status: type: string enum: - working - failed - canceled description: >- `working` while the agent works on it. `failed` or `canceled` when the run ended before the prompt finished. required: - run_id - index - text - submitted_at - status additionalProperties: false description: A prompt the agent has not finished. FinishedPrompt: type: object properties: run_id: $ref: '#/components/schemas/RunId' index: type: integer minimum: 1 maximum: 9007199254740991 description: Position of the prompt in its run, starting at 1. text: type: string description: What you asked the agent to do. model: type: string description: Model for this prompt, when not the run's. submitted_at: type: string status: type: string enum: - finished description: The agent stopped, whatever its exit code. finished_at: type: string exit_code: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Exit code of the agent. required: - run_id - index - text - submitted_at - status - finished_at - exit_code additionalProperties: false description: A prompt the agent has finished. FailureKind: type: string enum: - repository_checkout_failed - setup_failed - browser_not_started - sandbox_not_found - process_lost - sandbox_unavailable - agent_stopped - unexpected description: >- What kind of thing went wrong: the repository could not be checked out, the environment's setup command failed, the browser did not start, the sandbox disappeared, the agent's process was lost, the sandbox provider failed, the agent of a run that accepts no follow-ups stopped with an error, or something unexpected. RequestIssue: type: object properties: path: type: array items: anyOf: - type: string - type: number - type: string enum: - Infinity - '-Infinity' - NaN description: >- Keys leading to the wrong value inside that part of the request, such as `["agent", "model"]`. Empty when the problem concerns that part as a whole. message: type: string description: What is wrong with the value. required: - path - message additionalProperties: false description: One problem found in the request. Harness: type: string enum: - claude-code - claude-desktop - codex - codex-app - cursor description: >- The coding agent to run: `claude-code` (Claude Code), `claude-desktop` (Cowork, the agent workspace of Anthropic's Claude desktop app, for documents, research and longer tasks), `codex` (OpenAI's Codex CLI), `codex-app` (the Codex mode of OpenAI's ChatGPT desktop app, with its browser, computer-use and document tools) or `cursor` (Cursor's CLI). Skill: type: object properties: name: type: string description: Name of the skill. files: type: array items: type: string description: Paths of the files in the skill's folder. required: - name - files additionalProperties: false description: A skill the agent can load. McpServer: type: object properties: name: type: string description: Name the agent knows the MCP server by. url: type: string description: URL of the MCP server. connection_id: $ref: '#/components/schemas/ConnectionId_1' headers: type: array items: type: string description: >- Names of the headers we add to every request to the MCP server. Their values are never returned. required: - name - url - headers additionalProperties: false description: An MCP server the agent can use. ConnectionId_1: type: string description: The connection the agent uses it through, if any. securitySchemes: bearer: description: >- An API key of your organization, starting with `trk_`, sent as `Authorization: Bearer `. type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.