Task-runs

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
POST
GET
PATCH
POST
POST
POST
POST
POST
POST
POST
GET
GET
POST
POST
GET
PATCH
POST
GET
GET

List all tasks runs

Get a list of runs for a specific task.

Required API key scopes

task:read

Path parameters

  • task_id
    string

Query parameters

  • limit
    integer
    Default: 50
  • offset
    integer
    Default: 0

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/

Example response

Status 200 List of task runs
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
      "stage": "string",
      "branch": "string",
      "status": "string",
      "environment": "string",
      "runtime_adapter": "claude",
      "provider": "anthropic",
      "model": "string",
      "reasoning_effort": "low",
      "log_url": "http://example.com",
      "error_message": "string",
      "output": {},
      "state": {},
      "artifacts": [
        {
          "id": "string",
          "name": "string",
          "type": "string",
          "source": "string",
          "size": 0,
          "content_type": "string",
          "storage_path": "string",
          "uploaded_at": "string"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create tasks runs

Create a new run for a specific task without starting execution.

Required API key scopes

task:write

Path parameters

  • task_id
    string

Request parameters

  • environment
    Default: local
  • mode
    Default: background
  • branch
    stringnull
  • sandbox_environment_id
    string
  • pr_authorship_mode
  • run_source
  • signal_report_id
    string
  • runtime_adapter
  • model
    string
  • reasoning_effort
  • github_user_token
    string
  • initial_permission_mode
  • home_quick_action
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/\
	-d environment=undefined

Example response

Status 201 Created task run
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "string",
  "environment": "string",
  "runtime_adapter": "claude",
  "provider": "anthropic",
  "model": "string",
  "reasoning_effort": "low",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
Status 400 Invalid task run payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 429 Team is over its posthog_code usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Retrieve tasks runs

Retrieve a single run for a specific task.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/

Example response

Status 200 Task run
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "string",
  "environment": "string",
  "runtime_adapter": "claude",
  "provider": "anthropic",
  "model": "string",
  "reasoning_effort": "low",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
Status 404 Task run not found

Update tasks runs

API for managing task runs. Each run represents an execution of a task.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • status
  • branch
    stringnull
  • stage
    stringnull
  • output
  • state
  • state_remove_keys
    array
  • error_message
    stringnull
  • environment

Response


Example request

PATCH /api/projects/:project_id/tasks/:task_id/runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/\
	-d status=undefined

Example response

Status 200 Updated task run
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "string",
  "environment": "string",
  "runtime_adapter": "claude",
  "provider": "anthropic",
  "model": "string",
  "reasoning_effort": "low",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
Status 400 Invalid update data
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found

Create tasks runs append log

Append one or more log entries to the task run log array

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • entries
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/append_log
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/append_log/\
	-d entries="array"

Example response

Status 200 Run with updated log
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "string",
  "environment": "string",
  "runtime_adapter": "claude",
  "provider": "anthropic",
  "model": "string",
  "reasoning_effort": "low",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
Status 400 Invalid log entries
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Run not found

Create tasks runs artifacts

Persist task artifacts to S3 and attach them to the run manifest.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/\
	-d artifacts="array"

Example response

Status 200 Run with updated artifact manifest
RESPONSE
{
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ]
}
Status 400 Invalid artifact payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Run not found

Create tasks runs artifacts download

Streams artifact content for a task run artifact after validating that it belongs to the run.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • storage_path
    string

Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/download
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/download/\
	-d storage_path="string"

Example response

Status 200 Artifact content
Status 400 Invalid request
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Artifact not found

Create tasks runs artifacts finalize upload

Verify directly uploaded S3 objects and attach them to the run artifact manifest.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/finalize_upload
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/finalize_upload/\
	-d artifacts="array"

Example response

Status 200 Run with updated artifact manifest
RESPONSE
{
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ]
}
Status 400 Invalid artifact payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Run not found

Create tasks runs artifacts prepare upload

Reserve S3 object keys for task artifacts and return presigned POST forms for direct uploads.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/prepare_upload
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/prepare_upload/\
	-d artifacts="array"

Example response

Status 200 Prepared uploads for the requested artifacts
RESPONSE
{
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "expires_in": 0,
      "presigned_post": {
        "url": "http://example.com",
        "fields": {
          "property1": "string",
          "property2": "string"
        }
      }
    }
  ]
}
Status 400 Invalid artifact payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Run not found

Create tasks runs artifacts presign

Returns a temporary, signed URL that can be used to download a specific artifact.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • storage_path
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/presign
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/presign/\
	-d storage_path="string"

Example response

Status 200 Presigned URL for the requested artifact
RESPONSE
{
  "url": "http://example.com",
  "expires_in": 0
}
Status 400 Invalid request
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Artifact not found

Create tasks runs command

Queue user_message JSON-RPC commands through the task workflow and forward sandbox control commands to the agent server. Supports user_message, cancel, close, permission_response, and set_config_option commands.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • jsonrpc
  • method
  • params
    object
  • id

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/command
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/command/\
	-d jsonrpc=undefined,\
	-d method=undefined

Example response

Status 200 Agent server response
RESPONSE
{
  "jsonrpc": "string",
  "id": null,
  "result": {},
  "error": {}
}
Status 400 Invalid command or no active sandbox
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 502 Agent server unreachable
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Retrieve tasks runs connection token

Generate a JWT token for direct connection to the sandbox. Valid for 24 hours.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/connection_token
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/connection_token/

Example response

Status 200 Connection token for direct sandbox connection
RESPONSE
{
  "token": "string"
}
Status 404 Task run not found

Retrieve tasks runs logs

Fetch the logs for a task run as JSONL. If the run resumes from another (state.resume_from_run_id), each ancestor's log is concatenated first (oldest ancestor → ... → this run) so resume consumers see a single continuous history and can find the most recent git_checkpoint event regardless of which run emitted it.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/logs/

Example response

Status 200 Log content in JSONL format
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:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • text
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/relay_message
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/relay_message/\
	-d text="string"

Example response

Status 200 Relay accepted
RESPONSE
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:write

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/resume_in_cloud
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/resume_in_cloud/

Example response

Status 200 Run resumed in cloud
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "string",
  "environment": "string",
  "runtime_adapter": "claude",
  "provider": "anthropic",
  "model": "string",
  "reasoning_effort": "low",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
Status 400 Run already active or workflow failed
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 429 Team is over its posthog_code usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

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:read

Path parameters

  • id
    string
  • task_id
    string

Query parameters

  • after
    string
  • event_types
    string
  • exclude_types
    string
  • limit
    integer
    Default: 1000
  • offset
    integer
    Default: 0

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/session_logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/session_logs/

Example 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:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • output

Response


Example request

PATCH /api/projects/:project_id/tasks/:task_id/runs/:id/set_output
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/set_output/\
	-d output=undefined

Example response

Status 200 Run with updated output
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "string",
  "environment": "string",
  "runtime_adapter": "claude",
  "provider": "anthropic",
  "model": "string",
  "reasoning_effort": "low",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
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:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • pending_user_message
    string
  • pending_user_artifact_ids
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/start
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/start/\
	-d pending_user_message="string"

Example response

Status 200 Task with updated latest run
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "repository": "string",
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "ci_prompt": "string"
}
Status 400 Invalid start payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 429 Team is over its posthog_code usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Retrieve tasks runs stream

Server-Sent Events stream of task run events. Events carry an id: line (a Redis stream id) 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 without gaps or duplicates. Only treat the stream as complete when the run itself reaches a terminal status.

?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:read

Path parameters

  • id
    string
  • task_id
    string

Query parameters

  • start
    string

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/stream
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/stream/

Example 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.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/stream_token
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/stream_token/

Example response

Status 200 Run-scoped token for reading the live event stream via the agent-proxy
RESPONSE
{
  "token": "string",
  "stream_base_url": "string"
}
Status 404 Task run not found

Community questions

Questions about this page? or post a community question.