> ## 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. # Create a run > Starts a coding agent on your prompt in a fresh sandbox. A one-shot run, the default, ends when the agent finishes; otherwise the run waits `idle` for follow-up prompts until you end it or it times out. Send an `Idempotency-Key` header to retry without creating a second run. The run gets the label `started_by: key:`, with the id of the API key that created it, in place of any `started_by` you send. Runs start only while your organization's balance is above $0. ## OpenAPI ````yaml https://tracks.alpic.ai/api/openapi.json post /runs 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: post: tags: - Runs summary: Create a run description: >- Starts a coding agent on your prompt in a fresh sandbox. A one-shot run, the default, ends when the agent finishes; otherwise the run waits `idle` for follow-up prompts until you end it or it times out. Send an `Idempotency-Key` header to retry without creating a second run. The run gets the label `started_by: key:`, with the id of the API key that created it, in place of any `started_by` you send. Runs start only while your organization's balance is above $0. operationId: runs.create parameters: - name: idempotency-key in: header schema: type: string minLength: 1 maxLength: 255 description: >- A unique value you choose, up to 255 characters, to retry safely: a request with a key already used in your organization returns the run the first request created, without starting another, whatever its body. required: false requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRunInput' required: true responses: '201': 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' '402': description: >- Your organization's balance is $0 or below: add funds to start runs again. content: application/json: schema: $ref: '#/components/schemas/InsufficientBalanceEncoded' '403': description: >- Your organization cannot start runs after a dispute on one of its payments: contact us. content: application/json: schema: $ref: '#/components/schemas/OrganizationBlockedEncoded' '422': description: >- The agent cannot use this model. The message lists the models it can use. | A `connection_id` in `environment.mcp_servers` does not exist or is not `active`. | An input file is missing, expired, or inaccessible to your organization. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ModelNotOfferedEncoded' - $ref: '#/components/schemas/ConnectionUnusableEncoded' - $ref: '#/components/schemas/FileUnavailableEncoded' '503': description: >- The model provider could not be reached to check the model. Retry later. content: application/json: schema: $ref: '#/components/schemas/ModelProviderUnavailableEncoded' security: - bearer: [] components: schemas: CreateRunInput: type: object properties: agent: $ref: '#/components/schemas/Agent' prompt: type: string minLength: 1 description: What you ask the agent to do first. input_files: type: array items: type: string description: Reference returned when requesting a file upload. maxItems: 20 description: >- Up to 20 uploaded file ids, staged in the sandbox before setup and referenced in the first prompt. environment: $ref: '#/components/schemas/EnvironmentInput' 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 budget_usd: type: number minimum: 0.01 maximum: 10000 description: >- Maximum the run may spend, in US dollars. Defaults to a standard budget when omitted. The run ends with `budget_exceeded` once it is reached. one_shot: type: boolean description: >- Whether the run ends as soon as its first prompt finishes. Defaults to `true`. Set it to `false` to send follow-up prompts while the run is `idle`. idle_timeout_seconds: type: integer minimum: 120 maximum: 900 description: >- How long the run waits for a follow-up prompt before it ends with `idle_timeout`, in seconds, from 120 to 900. Defaults to 900. Only allowed when `one_shot` is `false`. time_limit_seconds: type: integer minimum: 60 maximum: 43200 description: >- Longest the run may last, in seconds from when it starts, from 60 to 43200. Defaults to 7200. Once reached, the run ends with `time_limit`, even in the middle of a prompt. required: - agent - prompt - environment additionalProperties: false 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 InsufficientBalanceEncoded: type: object properties: _tag: type: string enum: - InsufficientBalance message: type: string top_up_url: type: string description: Where to add funds to your organization's balance. required: - _tag - message - top_up_url additionalProperties: false OrganizationBlockedEncoded: type: object properties: _tag: type: string enum: - OrganizationBlocked message: type: string required: - _tag - message additionalProperties: false ModelNotOfferedEncoded: type: object properties: _tag: type: string enum: - ModelNotOffered message: type: string required: - _tag - message additionalProperties: false ConnectionUnusableEncoded: type: object properties: _tag: type: string enum: - ConnectionUnusable message: type: string required: - _tag - message additionalProperties: false FileUnavailableEncoded: type: object properties: _tag: type: string enum: - FileUnavailable message: type: string required: - _tag - message additionalProperties: false ModelProviderUnavailableEncoded: type: object properties: _tag: type: string enum: - ModelProviderUnavailable 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. EnvironmentInput: type: object properties: repository: type: string minLength: 1 description: URL of a Git repository to clone before the agent starts. variables: type: object additionalProperties: type: string maxLength: 32768 description: >- Environment variables set in every process of the agent, by name. Their values are never returned. Names match `^[A-Za-z_][A-Za-z0-9_]*$`; at most 100 variables of up to 32768 characters each. `PATH`, `HOME` and names starting with `ANTHROPIC_`, `CLAUDE_`, `OPENAI_`, `CODEX_` or `AGENT_RUNNER_` are reserved for running the agent. maxProperties: 100 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/SkillInput' maxItems: 20 mcp_servers: type: array items: $ref: '#/components/schemas/McpServerInput' maxItems: 20 browser: type: boolean additionalProperties: false RunId: type: string description: Unique identifier of the run. 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). SkillInput: type: object properties: name: type: string maxLength: 64 description: >- Name of the skill, unique in the run, matching `^[a-z0-9]+(-[a-z0-9]+)*$` and up to 64 characters, such as `release-notes`. `plugin-management` is reserved for running the agent. files: type: array items: $ref: '#/components/schemas/SkillFileInput' maxItems: 100 required: - name - files additionalProperties: false McpServerInput: anyOf: - $ref: '#/components/schemas/McpServerByUrlInput' - $ref: '#/components/schemas/McpServerByConnectionInput' description: >- An MCP server the agent can use, reached through us: credentials never enter the sandbox. Set `url`, with `headers` if it takes an API key, or `connection_id`. 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. SkillFileInput: type: object properties: path: type: string maxLength: 200 content: type: string description: Text of the file. A file starting with `#!` is made executable. required: - path - content additionalProperties: false description: A text file of a skill. McpServerByUrlInput: type: object properties: name: type: string description: >- Name the agent knows the MCP server by, unique in the run, matching `^[A-Za-z0-9_-]{1,64}$`, such as `linear`. `chatgpt_plugins` is reserved for running the agent. url: type: string headers: type: object additionalProperties: type: string maxLength: 8192 description: >- Headers we add to every request to the MCP server, typically its API key, such as `{ "Authorization": "Bearer …" }` or `{ "x-api-key": "…" }`. They never enter the sandbox and their values are never returned. Names match `^[A-Za-z0-9-]{1,64}$`; at most 20 headers of up to 8192 characters each, on one line. minProperties: 1 maxProperties: 20 propertyNames: type: string connection_id: not: {} required: - name - url additionalProperties: false description: An MCP server given by its URL. McpServerByConnectionInput: type: object properties: name: type: string description: >- Name the agent knows the MCP server by, unique in the run, matching `^[A-Za-z0-9_-]{1,64}$`, such as `linear`. `chatgpt_plugins` is reserved for running the agent. connection_id: $ref: '#/components/schemas/ConnectionId' url: not: {} headers: not: {} required: - name - connection_id additionalProperties: false description: >- An MCP server given by a connection to it, called as the user who consented. ConnectionId_1: type: string description: The connection the agent uses it through, if any. ConnectionId: type: string description: >- An `active` connection: the agent uses its MCP server as the user who consented. 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.