S D K

Endpoints called by job executors using run tokens

Pause a run to wait for an external event

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

event_key*string

Globally unique key for the event trigger.

timeout_secs?integer

Timeout in seconds before the trigger expires.

Default3600

notify_url?string

Optional webhook URL to notify when the event trigger is created.

Formaturi

Response Body

`application/json`

curl -X POST "http://localhost:8080/sdk/v1/runs/string/wait-for-event" \  -H "Content-Type: application/json" \  -d '{    "event_key": "string"  }'

{
  "status": "waiting",
  "event_key": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "trigger_id": "string"
}

Empty

Get run payload

Authorization

RunToken

Path Parameters

runID*string

Response Body

`application/json`

curl -X GET "http://localhost:8080/sdk/v1/runs/string/payload"

{}

Empty

Log an event

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

message?string

level?string

data?object

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/log" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Report progress

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

percent?integer

message?string

step?string

eta_secs?integer

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/progress" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Send heartbeat

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/heartbeat"

Empty

Attach annotations

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

[key: string]?string

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/annotate" \  -H "Content-Type: application/json" \  -d '{    "property1": "string",    "property2": "string"  }'

Empty

Save a checkpoint

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

source?string

state?object

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/checkpoint" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Report AI model usage

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*string

model*string

prompt_tokens?integer

completion_tokens?integer

total_tokens?integer

cost_microusd?integer

Formatint64

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/usage" \  -H "Content-Type: application/json" \  -d '{    "provider": "string",    "model": "string"  }'

Empty

Record a tool call

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tool_name?string

input?object

output?object

duration_ms?integer

status?string

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/tool-call" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Upsert structured output

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

output_key?string

schema?object

value?object

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/output" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Mark run completed

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

result?object

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/complete" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Mark run failed

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

error?string

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/fail" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Spawn a child job run

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

job_id?string

payload?object

priority?integer

Response Body

`application/json`

curl -X POST "http://localhost:8080/sdk/v1/runs/string/spawn" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "string",
  "job_id": "string",
  "project_id": "string",
  "status": "delayed",
  "attempt": 0,
  "payload": {},
  "result": {},
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "error": "string",
  "triggered_by": "string",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z",
  "heartbeat_at": "2019-08-24T14:15:22Z",
  "next_retry_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "parent_run_id": "string",
  "priority": 0,
  "idempotency_key": "string",
  "job_version": 0,
  "workflow_step_run_id": "string",
  "max_attempts_override": 0,
  "timeout_secs_override": 0,
  "retry_backoff": "string",
  "retry_initial_delay_secs": 0,
  "retry_max_delay_secs": 0,
  "execution_trace": {
    "queue_wait_ms": 0,
    "dequeue_ms": 0,
    "connect_ms": 0,
    "ttfb_ms": 0,
    "transfer_ms": 0,
    "total_ms": 0,
    "dispatch_ms": 0
  },
  "debug_mode": true,
  "continuation_of": "string",
  "lineage_depth": 0,
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "job_version_id": "string",
  "created_by": "string",
  "batch_id": "string",
  "concurrency_key": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

Create a continuation run

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

payload?object

Response Body

`application/json`

curl -X POST "http://localhost:8080/sdk/v1/runs/string/continue" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "string",
  "job_id": "string",
  "project_id": "string",
  "status": "delayed",
  "attempt": 0,
  "payload": {},
  "result": {},
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "error": "string",
  "triggered_by": "string",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z",
  "heartbeat_at": "2019-08-24T14:15:22Z",
  "next_retry_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "parent_run_id": "string",
  "priority": 0,
  "idempotency_key": "string",
  "job_version": 0,
  "workflow_step_run_id": "string",
  "max_attempts_override": 0,
  "timeout_secs_override": 0,
  "retry_backoff": "string",
  "retry_initial_delay_secs": 0,
  "retry_max_delay_secs": 0,
  "execution_trace": {
    "queue_wait_ms": 0,
    "dequeue_ms": 0,
    "connect_ms": 0,
    "ttfb_ms": 0,
    "transfer_ms": 0,
    "total_ms": 0,
    "dispatch_ms": 0
  },
  "debug_mode": true,
  "continuation_of": "string",
  "lineage_depth": 0,
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "job_version_id": "string",
  "created_by": "string",
  "batch_id": "string",
  "concurrency_key": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

List all run state keys

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Response Body

curl -X GET "http://localhost:8080/sdk/v1/runs/string/state"

Empty

Set run state key

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

key?string

value?object

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/state" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Get run state key

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

key*string

Response Body

curl -X GET "http://localhost:8080/sdk/v1/runs/string/state/string"

Empty

Delete run state key

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

key*string

Response Body

curl -X DELETE "http://localhost:8080/sdk/v1/runs/string/state/string"

Empty

Report in-container resource usage

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

memory_mb?number

Formatdouble

memory_percent?number

Formatdouble

cpu_percent?number

Formatdouble

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/resources" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Push LLM stream chunk

Authorization

runToken

AuthorizationBearer <token>

JWT run token issued by the trigger response.

In: header

Path Parameters

runID*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

chunk?string

stream_id?string

done?boolean

Response Body

curl -X POST "http://localhost:8080/sdk/v1/runs/string/stream" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Was this page helpful?

200application/json

400

404

409

200application/json

404

200

200

200

200

200

200

200

200

200

200

202application/json

202application/json

200

201

200

204

201

200

`application/json`

`application/json`

`application/json`

`application/json`