Tasks

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`POST`
`POST`
`POST`
`POST`
`GET`
`GET`

← Previous pageNext 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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/".format(
        project_id=project_id,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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
    }
  ]
}

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/".format(
        project_id=project_id,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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
array | null
relayed_mcp_servers
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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/".format(
        project_id=project_id,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"imported_mcp_servers": "array"
	}
).json()

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
}

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
array | null
relayed_mcp_servers
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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/".format(
        project_id=project_id,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"imported_mcp_servers": "array"
	}
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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
error_type

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
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

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

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
error_type

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
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/analysis-activity/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"goal": "string",
		"evidence": "string",
		"start_line": "integer",
		"end_line": "integer",
		"tool_calls": "integer",
		"failed_calls": "integer",
		"seconds": "integer",
		"idle_seconds": "integer"
	}
).json()

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 analysis activity

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/analysis-activity/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"goal": "string",
		"evidence": "string",
		"start_line": "integer",
		"end_line": "integer",
		"tool_calls": "integer",
		"failed_calls": "integer",
		"seconds": "integer",
		"idle_seconds": "integer"
	}
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/analyze/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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 analyze

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/analyze/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/append_log/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"entries": "array"
	}
).json()

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 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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/append_log/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"entries": "array"
	}
).json()

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
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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/artifacts/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"artifacts": "array"
	}
).json()

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

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
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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/artifacts/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"artifacts": "array"
	}
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/artifacts/{artifact_id}/download/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		artifact_id="<the artifact id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/artifacts/{artifact_id}/download/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		artifact_id="<the artifact id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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

Retrieve tasks runs artifacts preview

Returns a short-lived URL for one HTML artifact version on the artifact origin. The page runs its scripts only when scripts=true.

Required API key scopes

task:read

Path parameters

artifact_id
string
id
string
task_id
string

Query parameters

scripts
boolean
version
integer

Response

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/:artifact_id/preview
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/preview/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/artifacts/{artifact_id}/preview/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		artifact_id="<the artifact id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "url": "http://example.com",
  "scripts_available": true
}

Status 400 Invalid version or scripts value

Status 403 Scripts or analytics data are not available to the caller

Status 404 HTML artifact not found

Status 503 Artifact preview origin unavailable

Retrieve tasks runs artifacts preview

Returns a short-lived URL for one HTML artifact version on the artifact origin. The page runs its scripts only when scripts=true.

Required API key scopes

task:read

Path parameters

artifact_id
string
id
string
task_id
string

Query parameters

scripts
boolean
version
integer

Response

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/:artifact_id/preview
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/preview/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/tasks/{task_id}/runs/{tasks-3_id}/artifacts/{artifact_id}/preview/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		artifact_id="<the artifact id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "url": "http://example.com",
  "scripts_available": true
}