Task-runs

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

Endpoints

GET
POST
GET
PATCH
POST
POST
POST
POST
GET
POST
POST
POST
POST
POST
POST
POST
POST
POST
GET
GET
Next page →

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": "off",
      "log_url": "http://example.com",
      "error_message": "string",
      "output": {},
      "task_summary": "string",
      "task_tags": [
        "string"
      ],
      "state": {},
      "artifacts": [
        {
          "id": "string",
          "name": "string",
          "type": "string",
          "source": "string",
          "size": 0,
          "content_type": "string",
          "metadata": {
            "skill_name": "string",
            "skill_source": "user",
            "content_sha256": "string",
            "bundle_format": "zip",
            "schema_version": 1
          },
          "storage_path": "string",
          "uploaded_at": "string",
          "uploaded_by": "agent",
          "uploaded_by_user_id": 0,
          "dismissed_at": "string",
          "url": "http://example.com"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "scheduled_at": "2019-08-24T14:15:22Z",
      "preview_available": true
    }
  ]
}

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

  • imported_mcp_servers
    Click to open
    array | null
  • relayed_mcp_servers
    Click to open
    array | null
  • rtk_enabled
    boolean | null
  • benjamin_enabled
    boolean | null
  • claude_model_access
  • codex_model_access
  • environment
    Default: local
  • mode
    Default: background
  • branch
    string | null
  • sandbox_environment_id
    string
  • custom_image_id
    string
  • pr_authorship_mode
  • auto_publish
    boolean | null
  • run_source
  • signal_report_id
    string
  • runtime_adapter
  • model
    string
  • reasoning_effort
  • context_window
  • fast_mode
    boolean | null
  • github_user_token
    string
  • initial_permission_mode

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 imported_mcp_servers="array"

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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "task_summary": "string",
  "task_tags": [
    "string"
  ],
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "preview_available": true
}
Status 400 Invalid task run payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 403 PostHog Desktop access is required, or Pi cloud runtime is disabled
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "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",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 503 PostHog Desktop access could not be verified
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "task_summary": "string",
  "task_tags": [
    "string"
  ],
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "preview_available": true
}
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
    string | null
  • stage
    string | null
  • output
  • state
    object
  • state_remove_keys
    array
  • state_append
    object
  • error_message
    string | null

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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "task_summary": "string",
  "task_tags": [
    "string"
  ],
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "preview_available": true
}
Status 400 Invalid update data
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found

Create tasks runs analysis activity

Store one activity record on a task-analysis run. Only the run's own task-bound sandbox agent may call it, and only on a task-analysis run. Activities arrive in log order and do not overlap. An exact repeat of a stored activity returns its index without storing it again. The activities list is server-owned: it is not writable through the run update endpoint.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • goal_kind
  • goal
    string
  • outcome
  • blocker_kind
  • blocker_name
    string | null
  • repair
    string | null
  • evidence
    string
  • start_line
    integer
  • end_line
    integer
  • tool_calls
    integer
  • failed_calls
    integer
  • seconds
    integer
  • idle_seconds
    integer
  • commands
    array
  • guidance_read
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/analysis-activity
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/analysis-activity/\
	-d goal_kind=undefined,\
	-d goal="string",\
	-d outcome=undefined,\
	-d evidence="string",\
	-d start_line="integer",\
	-d end_line="integer",\
	-d tool_calls="integer",\
	-d failed_calls="integer",\
	-d seconds="integer",\
	-d idle_seconds="integer"

Example response

Status 201 Activity stored on the run, or the index of the identical activity already stored
RESPONSE
{
  "activity_index": 0
}
Status 400 The activity is invalid, overlaps a stored activity, or the run already holds the maximum
Status 403 Only the run's own analysis sandbox may report activities
Status 404 Run not found

Create tasks runs analyze

Create a PostHog-funded analysis task that reviews this run's transcript for inefficiencies and reports findings. Idempotent per run: if an analysis task already exists for this run, it is returned instead of creating another. The analysis is not billed to the customer.

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/analyze
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/analyze/

Example response

Status 200 An analysis task already exists for this run
RESPONSE
{
  "analysis_task_id": "81cf5f8c-71fa-41eb-91f0-8d6f588be26e",
  "created": true
}
Status 201 Analysis task created
RESPONSE
{
  "analysis_task_id": "81cf5f8c-71fa-41eb-91f0-8d6f588be26e",
  "created": true
}
Status 400 The run cannot be analyzed (for example, it has no log yet)
Status 403 AI data processing is not approved for this organization
Status 404 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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "task_summary": "string",
  "task_tags": [
    "string"
  ],
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "preview_available": true
}
Status 400 Invalid log entries
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Run not found
Status 503 Log is locked by another append; retry
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

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",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ]
}
Status 400 Invalid artifact payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Run not found

Retrieve tasks runs artifacts download

Redirects to a short-lived presigned URL for the artifact, so callers can share a stable link instead of a raw presigned URL.

Required API key scopes

task:read

Path parameters

  • artifact_id
    string
  • id
    string
  • task_id
    string

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/:artifact_id/download
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/artifacts/:artifact_id/download/

Example response

Status 302 Redirect to a short-lived presigned download URL
Status 400 Unable to generate download URL
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Artifact not found

Create tasks runs artifacts dismiss

Hides artifacts from clients without deleting them from storage, so a file dismissed by mistake can be restored.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • artifact_ids
    array
  • dismissed
    boolean
    Default: true

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/dismiss
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/dismiss/\
	-d artifact_ids="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",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ]
}
Status 404 Artifact 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",
  "retry_token": "string",
  "reason": "startup_plan",
  "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",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ]
}
Status 400 Invalid artifact payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "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",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "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",
  "retry_token": "string",
  "reason": "startup_plan",
  "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",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Artifact not found

Create tasks runs artifacts references

Attach live PostHog object references to the run artifact manifest without uploading files.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • references
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/references
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/references/\
	-d references="array"

Example response

Status 200 Run with updated reference artifacts
RESPONSE
{
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ]
}
Status 404 Run not found

Create tasks runs cancel

Stop an active cloud run. Interrupts the agent, snapshots interactive sessions for later resume, tears down the sandbox, and marks the run cancelled. Idempotent: cancelling a finished run returns it unchanged.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • reason
    string | null
  • only_if_awaiting_first_message
    boolean
    Default: false

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/cancel
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/cancel/\
	-d reason="string"

Example response

Status 200 Run already finished, or `only_if_awaiting_first_message` was set and the run has since received its first message; returned unchanged
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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "task_summary": "string",
  "task_tags": [
    "string"
  ],
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "preview_available": true
}
Status 202 Cancellation accepted
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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "task_summary": "string",
  "task_tags": [
    "string"
  ],
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "preview_available": true
}
Status 400 Run is not a cloud run
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 503 Cancellation could not be delivered; safe to retry
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Create tasks runs clear conversation

Record a /clear boundary in a finished run's log so the next run in the chain starts with an empty conversation. Its artifacts and visible history are unaffected. Only for a finished run: an active one has an agent that owns the clear, so send /clear to it as an ordinary message instead.

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/clear_conversation
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/clear_conversation/

Example response

Status 200 Run with the boundary recorded
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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "task_summary": "string",
  "task_tags": [
    "string"
  ],
  "state": {},
  "artifacts": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "source": "string",
      "size": 0,
      "content_type": "string",
      "metadata": {
        "skill_name": "string",
        "skill_source": "user",
        "content_sha256": "string",
        "bundle_format": "zip",
        "schema_version": 1
      },
      "storage_path": "string",
      "uploaded_at": "string",
      "uploaded_by": "agent",
      "uploaded_by_user_id": 0,
      "dismissed_at": "string",
      "url": "http://example.com"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "preview_available": true
}
Status 404 Run not found
Status 409 Run is still active; send /clear to its agent
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 503 Log is locked by another append; retry
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

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, set_config_option, mcp_response, side_question, native Pi RPC commands, and Pi queue operations. Retry loop: a 503 is transient (sandbox_not_ready means the command arrived before the live run's command channel came up; agent_session_not_ready means an approval was rejected before execution while the agent starts) — retry it until the request you are answering expires. A 502 (agent server unreachable) or 504 (agent server timed out) means delivery is unknown; retry only when the command method is safe to retry. A 409 run_ended is final: the run is over and its sandbox is gone. HTTP 200 preserves JSON-RPC errors; permission acceptance requires result.resolved=true.

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": null,
  "error": {}
}
Status 400 Invalid command — fatal, do not retry. (Legacy exception: interactive PostHog Desktop grants still receive the transient `sandbox_not_ready` condition as a 400 for every method except `credential_response`, because shipped Desktop builds branch on that status; API callers always get it as a 503.)
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 403 PostHog Desktop access is required to message this run's agent
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 409 Final, do not retry. Task run workflow has ended; `permission_target_ended` for an ended approval target; `run_ended` when the run is completed, failed, or cancelled and its sandbox is cleaned up — unlike `sandbox_not_ready`, nothing will ever come up
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 429 Organization reached its PostHog Desktop usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 502 Agent server unreachable
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 503 Transient, retry after `Retry-After` until the request you are answering expires. Code `sandbox_not_ready`: the run is still live but its sandbox's command channel is not reachable yet — the usual answer to a command sent as soon as the run asks for one, such as a credential_response (a 409 `run_ended` ends that loop). Code `agent_session_not_ready`: approval rejected before execution while the agent starts. Or PostHog Desktop access could not be verified.
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "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 403 PostHog Desktop access is required
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 429 Organization reached its PostHog Desktop usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 503 PostHog Desktop access could not be verified
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

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.

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
Next page →