Task-runs
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
GET | |
POST | |
GET | |
POST | |
POST | |
GET | |
PATCH | |
PATCH | |
POST | |
GET | |
GET | |
POST | |
GET | |
POST |
Retrieve tasks runs peers
Agent runs this run may send messages to: cloud Pi runs of tasks created by the same user, currently in progress or queued. Discovery and send validation share one visibility policy, so a run can only message what it can list; the per-entry sendable flag is the liveness contract.
Required API key scopes
task:readPath parameters
- idstring
- task_idstring
Response
Example request
GET /api /projects /:project_id /tasks /:task_id /runs /:id /peersExample response
Status 200 Active agent runs this run may message
Status 403 Peer messaging is disabled or the task is not on the Pi runtime
Status 404 Run not found
Create tasks runs peers message
Relay a message from this run to a peer agent run. The body is delivered below a server-composed provenance envelope as a queued (non-steer) turn; attachments are copied into the target run's own artifact storage. accepted means queued for delivery, never delivered — the sandbox handoff happens later inside the target's workflow.
Required API key scopes
task:writePath parameters
- idstring
- target_run_idstring
- task_idstring
Request parameters
- contentstring
- artifact_idsarray
Response
Example request
POST /api /projects /:project_id /tasks /:task_id /runs /:id /peers /:target_run_id /messageExample response
Status 200 Synchronous send result (accepted / target_finished / rejected)
Status 400 Invalid message payload
Status 403 Peer messaging is disabled or the task is not on the Pi runtime
Status 404 Run not found
Retrieve tasks runs preview
Redirects to the PostHog dev stack running inside this run's sandbox. A fresh sandbox access token is minted on every request and carried only in the redirect target, so it is never persisted or returned in a response body. When the run has no preview, or its sandbox has stopped, this renders a short HTML page instead.
Required API key scopes
task:writePath parameters
- idstring
- task_idstring
Example request
GET /api /projects /:project_id /tasks /:task_id /runs /:id /previewExample response
Status 200 HTML page explaining that the preview is not ready yet or has ended
Status 302 Redirect to the sandbox preview with a freshly minted access token
Status 403 Refused during read-only impersonation
Status 404 Task run not found
Create tasks runs relay message
Queue a Slack relay workflow to post a run message into the mapped Slack thread.
Required API key scopes
task:writePath parameters
- idstring
- task_idstring
Request parameters
- textstring
- message_idstring | null
- text_partsarray
- trace_idstring | null
Response
Example request
POST /api /projects /:project_id /tasks /:task_id /runs /:id /relay_messageExample response
Status 200 Relay accepted
Status 404 Run not found
Create tasks runs resume in cloud
Resume an existing task run in a cloud sandbox. Terminates any existing workflow and starts a new one.
Required API key scopes
task:writePath parameters
- idstring
- task_idstring
Response
Example request
POST /api /projects /:project_id /tasks /:task_id /runs /:id /resume_in_cloudExample response
Status 200 Run resumed in cloud
Status 400 Run already active or workflow failed
Status 403 PostHog Desktop access is required, or Pi cloud runtime is disabled
Status 429 Team is over its posthog_code usage limit
Status 503 PostHog Desktop access could not be verified
Retrieve tasks runs session logs
Fetch session log entries for a task run with optional filtering by timestamp, event type, and limit.
Required API key scopes
task:readPath parameters
- idstring
- task_idstring
Query parameters
- afterstring
- event_typesstring
- exclude_typesstring
- limitintegerDefault:
1000 - offsetintegerDefault:
0
Example request
GET /api /projects /:project_id /tasks /:task_id /runs /:id /session_logsExample response
Status 200 Filtered log events as JSON array
Status 404 Task run not found
Update tasks runs set output
Update the output field for a task run (e.g., PR URL, commit SHA, etc.)
Required API key scopes
task:writePath parameters
- idstring
- task_idstring
Request parameters
- output
Response
Example request
PATCH /api /projects /:project_id /tasks /:task_id /runs /:id /set_outputExample response
Status 200 Run with updated output
Status 404 Run not found
Update tasks runs set summary
Replace the running summary for a task run, and optionally its slug tags.
Required API key scopes
task:writePath parameters
- idstring
- task_idstring
Request parameters
- summarystring
- tagsarray
Response
Example request
PATCH /api /projects /:project_id /tasks /:task_id /runs /:id /set_summaryExample response
Status 200 Run with updated task summary
Status 404 Run not found
Create tasks runs start
Start an existing cloud run after any initial run-scoped attachments have been uploaded.
Required API key scopes
task:writePath parameters
- idstring
- task_idstring
Request parameters
- pending_user_messagestring
- pending_user_artifact_idsarray
Response
Example request
POST /api /projects /:project_id /tasks /:task_id /runs /:id /startExample response
Status 200 Task with updated latest run
Status 400 Invalid start payload
Status 403 PostHog Desktop access is required, or Pi cloud runtime is disabled
Status 404 Task run not found
Status 429 Team is over its posthog_code usage limit
Status 503 PostHog Desktop access could not be verified
Retrieve tasks runs stream
Server-Sent Events stream of task run events. Events carry an id: line (a Redis stream id, or a synthetic log-<n> id during backlog replay) usable as a resume cursor.
The server caps each connection at 900 seconds: it emits event: end with data: {"type": "rotated"} and closes. This does NOT mean the run finished — reconnect with the Last-Event-ID header set to the last received event id to resume. Only treat the stream as complete when the run itself reaches a terminal status.
Resume guarantees cover mirrored events only: on runs where live mirroring is presence-gated, events produced while no viewer was connected are not in the live stream. Reload the run's session logs to recover the agent's output; run-state and progress frames are not in those logs, so refetch the run itself for its current state.
On runs with durable backlog serving, a connection without Last-Event-ID first replays history from the run log under synthetic log-<n> event ids, then attaches the live stream, skipping live entries the backlog already covered. Reconnecting with a log-<n> id resumes the backlog replay from that point; reconnecting with a Redis id resumes the live stream, may re-deliver a few events already served as backlog frames, and falls back to a full backlog replay when the resume point was trimmed or the stream expired. Runs whose log exceeds the backlog byte cap skip the replay and serve only the recent live window. When the backlog is temporarily unavailable (a storage read failure, or a worker at its concurrent replay budget), the stream emits an event: error frame and closes; reconnect with the same cursor to retry. Treat delivery as at-least-once across reconnects.
?start=latest consumers must also carry Last-Event-ID across reconnects: reconnecting without it re-resolves to the then-current latest event, silently skipping anything published while disconnected.
SDK consumers: do not call the generated fetch wrapper for this path — it will buffer the entire stream. Use the URL builder (getTasksRunsStreamRetrieveUrl) with a streaming fetch/EventSource-style consumer and the Last-Event-ID header instead.
Required API key scopes
task:readPath parameters
- idstring
- task_idstring
Query parameters
- startstring
Example request
GET /api /projects /:project_id /tasks /:task_id /runs /:id /streamExample response
Status 200
Retrieve tasks runs stream token
Generate a run-scoped JWT that authorizes reading this task run's live event stream via the agent-proxy. A run that keeps only a short live tail in Redis is routed to the proxy only when the client sets resync=true, meaning it rebuilds from the durable run log when the proxy reports a trimmed cursor.
Required API key scopes
task:readPath parameters
- idstring
- task_idstring
Query parameters
- resyncbooleanDefault:
false
Response
Example request
GET /api /projects /:project_id /tasks /:task_id /runs /:id /stream_tokenExample response
Status 200 Run-scoped token for reading the live event stream via the agent-proxy
Status 404 Task run not found
Create tasks runs subscription token
Give the run's agent-server a short-lived ChatGPT access token from the run owner's connected account. Only the run's sandbox may call this, and it must present the run token it received at launch. Send the digest of a token Codex rejected so the server refreshes it early, once.
Required API key scopes
task:writePath parameters
- idstring
- task_idstring
Request parameters
- rejected_access_token_sha256string | null
Response
Example request
POST /api /projects /:project_id /tasks /:task_id /runs /:id /subscription_tokenExample response
Status 200 Short-lived ChatGPT access token for this run
Status 400 Missing required header
Status 403 Caller is not this run's sandbox, or the run token is invalid
Status 404 Task run not found
Status 409 reauth_required: the run owner must reconnect their ChatGPT account
Status 502 openai_unavailable: OpenAI did not answer the token refresh
Retrieve tasks runs task session
API for managing task runs. Each run represents an execution of a task.
Required API key scopes
task:readPath parameters
- idstring
- task_idstring
Response
Example request
GET /api /projects /:project_id /tasks /:task_id /runs /:id /task_sessionExample response
Status 200
Status 404 Task session not found
Create tasks runs task session sync
API for managing task runs. Each run represents an execution of a task.
Required API key scopes
task:writePath parameters
- idstring
- task_idstring