Create a run

curl --request POST \
  --url https://tracks.alpic.ai/api/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent": {
    "model": "<string>"
  },
  "prompt": "<string>",
  "environment": {
    "repository": "<string>",
    "variables": {},
    "setup": "<string>",
    "teardown": "<string>",
    "skills": [
      {
        "name": "<string>",
        "files": [
          {
            "path": "<string>",
            "content": "<string>"
          }
        ]
      }
    ],
    "mcp_servers": [
      {
        "name": "<string>",
        "url": "<string>",
        "connection_id": "<unknown>"
      }
    ],
    "browser": true
  },
  "input_files": [
    "<string>"
  ],
  "labels": {},
  "budget_usd": 5000.005,
  "one_shot": true,
  "idle_timeout_seconds": 510,
  "time_limit_seconds": 21630
}
'

import requests

url = "https://tracks.alpic.ai/api/runs"

payload = {
    "agent": { "model": "<string>" },
    "prompt": "<string>",
    "environment": {
        "repository": "<string>",
        "variables": {},
        "setup": "<string>",
        "teardown": "<string>",
        "skills": [
            {
                "name": "<string>",
                "files": [
                    {
                        "path": "<string>",
                        "content": "<string>"
                    }
                ]
            }
        ],
        "mcp_servers": [
            {
                "name": "<string>",
                "url": "<string>",
                "connection_id": "<unknown>"
            }
        ],
        "browser": True
    },
    "input_files": ["<string>"],
    "labels": {},
    "budget_usd": 5000.005,
    "one_shot": True,
    "idle_timeout_seconds": 510,
    "time_limit_seconds": 21630
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent: {model: '<string>'},
    prompt: '<string>',
    environment: {
      repository: '<string>',
      variables: {},
      setup: '<string>',
      teardown: '<string>',
      skills: [{name: '<string>', files: [{path: '<string>', content: '<string>'}]}],
      mcp_servers: [{name: '<string>', url: '<string>', connection_id: '<unknown>'}],
      browser: true
    },
    input_files: ['<string>'],
    labels: {},
    budget_usd: 5000.005,
    one_shot: true,
    idle_timeout_seconds: 510,
    time_limit_seconds: 21630
  })
};

fetch('https://tracks.alpic.ai/api/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://tracks.alpic.ai/api/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent' => [
        'model' => '<string>'
    ],
    'prompt' => '<string>',
    'environment' => [
        'repository' => '<string>',
        'variables' => [
                
        ],
        'setup' => '<string>',
        'teardown' => '<string>',
        'skills' => [
                [
                                'name' => '<string>',
                                'files' => [
                                                                [
                                                                                                                                'path' => '<string>',
                                                                                                                                'content' => '<string>'
                                                                ]
                                ]
                ]
        ],
        'mcp_servers' => [
                [
                                'name' => '<string>',
                                'url' => '<string>',
                                'connection_id' => '<unknown>'
                ]
        ],
        'browser' => true
    ],
    'input_files' => [
        '<string>'
    ],
    'labels' => [
        
    ],
    'budget_usd' => 5000.005,
    'one_shot' => true,
    'idle_timeout_seconds' => 510,
    'time_limit_seconds' => 21630
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tracks.alpic.ai/api/runs"

	payload := strings.NewReader("{\n  \"agent\": {\n    \"model\": \"<string>\"\n  },\n  \"prompt\": \"<string>\",\n  \"environment\": {\n    \"repository\": \"<string>\",\n    \"variables\": {},\n    \"setup\": \"<string>\",\n    \"teardown\": \"<string>\",\n    \"skills\": [\n      {\n        \"name\": \"<string>\",\n        \"files\": [\n          {\n            \"path\": \"<string>\",\n            \"content\": \"<string>\"\n          }\n        ]\n      }\n    ],\n    \"mcp_servers\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"connection_id\": \"<unknown>\"\n      }\n    ],\n    \"browser\": true\n  },\n  \"input_files\": [\n    \"<string>\"\n  ],\n  \"labels\": {},\n  \"budget_usd\": 5000.005,\n  \"one_shot\": true,\n  \"idle_timeout_seconds\": 510,\n  \"time_limit_seconds\": 21630\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://tracks.alpic.ai/api/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent\": {\n    \"model\": \"<string>\"\n  },\n  \"prompt\": \"<string>\",\n  \"environment\": {\n    \"repository\": \"<string>\",\n    \"variables\": {},\n    \"setup\": \"<string>\",\n    \"teardown\": \"<string>\",\n    \"skills\": [\n      {\n        \"name\": \"<string>\",\n        \"files\": [\n          {\n            \"path\": \"<string>\",\n            \"content\": \"<string>\"\n          }\n        ]\n      }\n    ],\n    \"mcp_servers\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"connection_id\": \"<unknown>\"\n      }\n    ],\n    \"browser\": true\n  },\n  \"input_files\": [\n    \"<string>\"\n  ],\n  \"labels\": {},\n  \"budget_usd\": 5000.005,\n  \"one_shot\": true,\n  \"idle_timeout_seconds\": 510,\n  \"time_limit_seconds\": 21630\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://tracks.alpic.ai/api/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent\": {\n    \"model\": \"<string>\"\n  },\n  \"prompt\": \"<string>\",\n  \"environment\": {\n    \"repository\": \"<string>\",\n    \"variables\": {},\n    \"setup\": \"<string>\",\n    \"teardown\": \"<string>\",\n    \"skills\": [\n      {\n        \"name\": \"<string>\",\n        \"files\": [\n          {\n            \"path\": \"<string>\",\n            \"content\": \"<string>\"\n          }\n        ]\n      }\n    ],\n    \"mcp_servers\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"connection_id\": \"<unknown>\"\n      }\n    ],\n    \"browser\": true\n  },\n  \"input_files\": [\n    \"<string>\"\n  ],\n  \"labels\": {},\n  \"budget_usd\": 5000.005,\n  \"one_shot\": true,\n  \"idle_timeout_seconds\": 510,\n  \"time_limit_seconds\": 21630\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "input_files": [
    {
      "id": "<string>",
      "name": "<string>",
      "content_type": "<string>",
      "size": 10485760,
      "path": "<string>",
      "download_url": "<string>",
      "download_expires_at": "<string>"
    }
  ],
  "labels": {},
  "agent": {
    "harness": "claude-code",
    "model": "<string>"
  },
  "environment": {
    "variables": [
      "<string>"
    ],
    "skills": [
      {
        "name": "<string>",
        "files": [
          "<string>"
        ]
      }
    ],
    "mcp_servers": [
      {
        "name": "<string>",
        "url": "<string>",
        "headers": [
          "<string>"
        ],
        "connection_id": "<string>"
      }
    ],
    "browser": true,
    "repository": "<string>",
    "setup": "<string>",
    "teardown": "<string>"
  },
  "budget_usd": 123,
  "one_shot": true,
  "time_limit_seconds": 0,
  "started_at": "<string>",
  "last_prompt": {
    "run_id": "<string>",
    "index": 4503599627370496,
    "text": "<string>",
    "submitted_at": "<string>",
    "status": "working",
    "model": "<string>"
  },
  "status": "preparing",
  "idle_timeout_seconds": 0
}

{
  "_tag": "InvalidRequest",
  "message": "<string>",
  "location": "path",
  "issues": [
    {
      "path": [
        "<string>"
      ],
      "message": "<string>"
    }
  ]
}

{
  "_tag": "ApiKeyRefused",
  "message": "<string>"
}

{
  "_tag": "InsufficientBalance",
  "message": "<string>",
  "top_up_url": "<string>"
}

{
  "_tag": "OrganizationBlocked",
  "message": "<string>"
}

{
  "_tag": "ModelNotOffered",
  "message": "<string>"
}

{
  "_tag": "ModelProviderUnavailable",
  "message": "<string>"
}

Runs

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:<id>, 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.

POST

runs

Create a run

curl --request POST \
  --url https://tracks.alpic.ai/api/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent": {
    "model": "<string>"
  },
  "prompt": "<string>",
  "environment": {
    "repository": "<string>",
    "variables": {},
    "setup": "<string>",
    "teardown": "<string>",
    "skills": [
      {
        "name": "<string>",
        "files": [
          {
            "path": "<string>",
            "content": "<string>"
          }
        ]
      }
    ],
    "mcp_servers": [
      {
        "name": "<string>",
        "url": "<string>",
        "connection_id": "<unknown>"
      }
    ],
    "browser": true
  },
  "input_files": [
    "<string>"
  ],
  "labels": {},
  "budget_usd": 5000.005,
  "one_shot": true,
  "idle_timeout_seconds": 510,
  "time_limit_seconds": 21630
}
'

import requests

url = "https://tracks.alpic.ai/api/runs"

payload = {
    "agent": { "model": "<string>" },
    "prompt": "<string>",
    "environment": {
        "repository": "<string>",
        "variables": {},
        "setup": "<string>",
        "teardown": "<string>",
        "skills": [
            {
                "name": "<string>",
                "files": [
                    {
                        "path": "<string>",
                        "content": "<string>"
                    }
                ]
            }
        ],
        "mcp_servers": [
            {
                "name": "<string>",
                "url": "<string>",
                "connection_id": "<unknown>"
            }
        ],
        "browser": True
    },
    "input_files": ["<string>"],
    "labels": {},
    "budget_usd": 5000.005,
    "one_shot": True,
    "idle_timeout_seconds": 510,
    "time_limit_seconds": 21630
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent: {model: '<string>'},
    prompt: '<string>',
    environment: {
      repository: '<string>',
      variables: {},
      setup: '<string>',
      teardown: '<string>',
      skills: [{name: '<string>', files: [{path: '<string>', content: '<string>'}]}],
      mcp_servers: [{name: '<string>', url: '<string>', connection_id: '<unknown>'}],
      browser: true
    },
    input_files: ['<string>'],
    labels: {},
    budget_usd: 5000.005,
    one_shot: true,
    idle_timeout_seconds: 510,
    time_limit_seconds: 21630
  })
};

fetch('https://tracks.alpic.ai/api/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://tracks.alpic.ai/api/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent' => [
        'model' => '<string>'
    ],
    'prompt' => '<string>',
    'environment' => [
        'repository' => '<string>',
        'variables' => [
                
        ],
        'setup' => '<string>',
        'teardown' => '<string>',
        'skills' => [
                [
                                'name' => '<string>',
                                'files' => [
                                                                [
                                                                                                                                'path' => '<string>',
                                                                                                                                'content' => '<string>'
                                                                ]
                                ]
                ]
        ],
        'mcp_servers' => [
                [
                                'name' => '<string>',
                                'url' => '<string>',
                                'connection_id' => '<unknown>'
                ]
        ],
        'browser' => true
    ],
    'input_files' => [
        '<string>'
    ],
    'labels' => [
        
    ],
    'budget_usd' => 5000.005,
    'one_shot' => true,
    'idle_timeout_seconds' => 510,
    'time_limit_seconds' => 21630
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tracks.alpic.ai/api/runs"

	payload := strings.NewReader("{\n  \"agent\": {\n    \"model\": \"<string>\"\n  },\n  \"prompt\": \"<string>\",\n  \"environment\": {\n    \"repository\": \"<string>\",\n    \"variables\": {},\n    \"setup\": \"<string>\",\n    \"teardown\": \"<string>\",\n    \"skills\": [\n      {\n        \"name\": \"<string>\",\n        \"files\": [\n          {\n            \"path\": \"<string>\",\n            \"content\": \"<string>\"\n          }\n        ]\n      }\n    ],\n    \"mcp_servers\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"connection_id\": \"<unknown>\"\n      }\n    ],\n    \"browser\": true\n  },\n  \"input_files\": [\n    \"<string>\"\n  ],\n  \"labels\": {},\n  \"budget_usd\": 5000.005,\n  \"one_shot\": true,\n  \"idle_timeout_seconds\": 510,\n  \"time_limit_seconds\": 21630\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://tracks.alpic.ai/api/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent\": {\n    \"model\": \"<string>\"\n  },\n  \"prompt\": \"<string>\",\n  \"environment\": {\n    \"repository\": \"<string>\",\n    \"variables\": {},\n    \"setup\": \"<string>\",\n    \"teardown\": \"<string>\",\n    \"skills\": [\n      {\n        \"name\": \"<string>\",\n        \"files\": [\n          {\n            \"path\": \"<string>\",\n            \"content\": \"<string>\"\n          }\n        ]\n      }\n    ],\n    \"mcp_servers\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"connection_id\": \"<unknown>\"\n      }\n    ],\n    \"browser\": true\n  },\n  \"input_files\": [\n    \"<string>\"\n  ],\n  \"labels\": {},\n  \"budget_usd\": 5000.005,\n  \"one_shot\": true,\n  \"idle_timeout_seconds\": 510,\n  \"time_limit_seconds\": 21630\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://tracks.alpic.ai/api/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent\": {\n    \"model\": \"<string>\"\n  },\n  \"prompt\": \"<string>\",\n  \"environment\": {\n    \"repository\": \"<string>\",\n    \"variables\": {},\n    \"setup\": \"<string>\",\n    \"teardown\": \"<string>\",\n    \"skills\": [\n      {\n        \"name\": \"<string>\",\n        \"files\": [\n          {\n            \"path\": \"<string>\",\n            \"content\": \"<string>\"\n          }\n        ]\n      }\n    ],\n    \"mcp_servers\": [\n      {\n        \"name\": \"<string>\",\n        \"url\": \"<string>\",\n        \"connection_id\": \"<unknown>\"\n      }\n    ],\n    \"browser\": true\n  },\n  \"input_files\": [\n    \"<string>\"\n  ],\n  \"labels\": {},\n  \"budget_usd\": 5000.005,\n  \"one_shot\": true,\n  \"idle_timeout_seconds\": 510,\n  \"time_limit_seconds\": 21630\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "input_files": [
    {
      "id": "<string>",
      "name": "<string>",
      "content_type": "<string>",
      "size": 10485760,
      "path": "<string>",
      "download_url": "<string>",
      "download_expires_at": "<string>"
    }
  ],
  "labels": {},
  "agent": {
    "harness": "claude-code",
    "model": "<string>"
  },
  "environment": {
    "variables": [
      "<string>"
    ],
    "skills": [
      {
        "name": "<string>",
        "files": [
          "<string>"
        ]
      }
    ],
    "mcp_servers": [
      {
        "name": "<string>",
        "url": "<string>",
        "headers": [
          "<string>"
        ],
        "connection_id": "<string>"
      }
    ],
    "browser": true,
    "repository": "<string>",
    "setup": "<string>",
    "teardown": "<string>"
  },
  "budget_usd": 123,
  "one_shot": true,
  "time_limit_seconds": 0,
  "started_at": "<string>",
  "last_prompt": {
    "run_id": "<string>",
    "index": 4503599627370496,
    "text": "<string>",
    "submitted_at": "<string>",
    "status": "working",
    "model": "<string>"
  },
  "status": "preparing",
  "idle_timeout_seconds": 0
}

{
  "_tag": "InvalidRequest",
  "message": "<string>",
  "location": "path",
  "issues": [
    {
      "path": [
        "<string>"
      ],
      "message": "<string>"
    }
  ]
}

{
  "_tag": "ApiKeyRefused",
  "message": "<string>"
}

{
  "_tag": "InsufficientBalance",
  "message": "<string>",
  "top_up_url": "<string>"
}

{
  "_tag": "OrganizationBlocked",
  "message": "<string>"
}

{
  "_tag": "ModelNotOffered",
  "message": "<string>"
}

{
  "_tag": "ModelProviderUnavailable",
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

An API key of your organization, starting with trk_, sent as Authorization: Bearer <key>.

Headers

idempotency-key

string

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 string length: 1 - 255

Body

application/json

agent

object

required

The coding agent and the model it uses.

Show child attributes

prompt

string

required

What you ask the agent to do first.

Minimum string length: 1

environment

object

required

Show child attributes

input_files

string[]

Up to 20 uploaded file ids, staged in the sandbox before setup and referenced in the first prompt.

Maximum array length: 20

Reference returned when requesting a file upload.

labels

object

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.

Show child attributes

budget_usd

number

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.

Required range: 0.01 <= x <= 10000

one_shot

boolean

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

integer

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.

Required range: 120 <= x <= 900

time_limit_seconds

integer

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 range: 60 <= x <= 43200

Response

A coding agent working on your prompt in an isolated sandbox.

Option 1
Option 2
Option 3

A coding agent working on your prompt in an isolated sandbox.

string

required

Unique identifier of the run.

input_files

object[]

required

Show child attributes

labels

object

required

Show child attributes

agent

object

required

The coding agent and the model it uses.

Show child attributes

environment

object

required

What the agent works on.

Show child attributes

budget_usd

required

one_shot

boolean

required

Whether the run ends as soon as its first prompt finishes.

time_limit_seconds

integer

required

Longest the run may last, in seconds from when it starts.

Required range: -9007199254740991 <= x <= 9007199254740991

started_at

string

required

last_prompt

object

required

One instruction to the agent and the work it did in response.

Option 1
Option 2

Show child attributes

status

enum<string>

required

preparing while its sandbox gets ready, working while the agent works on a prompt, idle while it waits for a follow-up prompt.

Available options:

preparing,

working,

idle

idle_timeout_seconds

integer

How long the run waits for a follow-up prompt before it ends, in seconds. Absent for a one-shot run.

Required range: -9007199254740991 <= x <= 9007199254740991

Overview

Runs

Files

Connections

Experiments

Executions

Library

System

Create a run

Authorizations

Headers

Body

Response