Tasks

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

Endpoints

POST
POST
DELETE
POST
POST
POST
GET
GET
POST
GET
PATCH
POST
POST
← Previous pageNext page →

Create tasks pin

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • pinned
    boolean

Response


Example request

POST /api/projects/:project_id/tasks/:id/pin
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/:id/pin/\
	-d pinned="boolean"

Example response

Status 200
RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "pinned": true
}

Create tasks pin

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • pinned
    boolean

Response


Example request

POST /api/projects/:project_id/tasks/:id/pin
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/:id/pin/\
	-d pinned="boolean"

Example response

Status 200
RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "pinned": true
}

Create tasks presence

Idempotent upsert: marks the calling user + device_id as actively watching this task for the next ~60 seconds. While at least one device for the user has a non-expired presence row for this task, the push fanout will skip ALL of that user's other registered devices for task notifications — the contract is 'if any device is demonstrably watching, suppress the others'. Clients call this every ~30s while the task screen is foregrounded. device_id is the UUID of the caller's UserPushToken row.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • device_id
    string

Example request

POST /api/projects/:project_id/tasks/:id/presence
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/:id/presence/\
	-d device_id="string"

Example response

Status 204 Presence recorded for this device.
Status 404 `device_id` does not match a push token registered by the caller.

Create tasks presence

Idempotent upsert: marks the calling user + device_id as actively watching this task for the next ~60 seconds. While at least one device for the user has a non-expired presence row for this task, the push fanout will skip ALL of that user's other registered devices for task notifications — the contract is 'if any device is demonstrably watching, suppress the others'. Clients call this every ~30s while the task screen is foregrounded. device_id is the UUID of the caller's UserPushToken row.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • device_id
    string

Example request

POST /api/projects/:project_id/tasks/:id/presence
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/:id/presence/\
	-d device_id="string"

Example response

Status 204 Presence recorded for this device.
Status 404 `device_id` does not match a push token registered by the caller.

Delete tasks presence

Idempotent upsert: marks the calling user + device_id as actively watching this task for the next ~60 seconds. While at least one device for the user has a non-expired presence row for this task, the push fanout will skip ALL of that user's other registered devices for task notifications — the contract is 'if any device is demonstrably watching, suppress the others'. Clients call this every ~30s while the task screen is foregrounded. device_id is the UUID of the caller's UserPushToken row.

Required API key scopes

task:write

Path parameters

  • id
    string

Example request

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

Example response

Status 204 Presence recorded for this device.
Status 404 `device_id` does not match a push token registered by the caller.

Delete tasks presence

Idempotent upsert: marks the calling user + device_id as actively watching this task for the next ~60 seconds. While at least one device for the user has a non-expired presence row for this task, the push fanout will skip ALL of that user's other registered devices for task notifications — the contract is 'if any device is demonstrably watching, suppress the others'. Clients call this every ~30s while the task screen is foregrounded. device_id is the UUID of the caller's UserPushToken row.

Required API key scopes

task:write

Path parameters

  • id
    string

Example request

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

Example response

Status 204 Presence recorded for this device.
Status 404 `device_id` does not match a push token registered by the caller.

Create tasks run

Create a new task run and kick off the workflow.

Required API key scopes

task:write

Path parameters

  • id
    string

Response


Example request

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",
  "runtime": "acp",
  "repository": "string",
  "repositories": [
    "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": {
    "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": {},
    "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"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_activity_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",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "slack_thread_references": [
    {
      "url": "string",
      "channel": "string",
      "created_at": "string"
    }
  ]
}
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 403 PostHog Desktop access is required, or Pi cloud runtime is disabled
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 not found
Status 429 Team is over its posthog_code usage limit, or the task's signal report has reached its task limit (code `signal_report_task_cap`)
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Create tasks run

Create a new task run and kick off the workflow.

Required API key scopes

task:write

Path parameters

  • id
    string

Response


Example request

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",
  "runtime": "acp",
  "repository": "string",
  "repositories": [
    "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": {
    "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": {},
    "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"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_activity_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",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "slack_thread_references": [
    {
      "url": "string",
      "channel": "string",
      "created_at": "string"
    }
  ]
}
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 403 PostHog Desktop access is required, or Pi cloud runtime is disabled
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 not found
Status 429 Team is over its posthog_code usage limit, or the task's signal report has reached its task limit (code `signal_report_task_cap`)
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Create tasks staged artifacts finalize upload

Verify staged S3 uploads and cache their metadata so they can be attached to the next run created for this task.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:id/staged_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/:id/staged_artifacts/finalize_upload/\
	-d artifacts="array"

Example response

Status 200 Finalized staged artifacts available for the next task run
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",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task not found

Create tasks staged artifacts finalize upload

Verify staged S3 uploads and cache their metadata so they can be attached to the next run created for this task.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:id/staged_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/:id/staged_artifacts/finalize_upload/\
	-d artifacts="array"

Example response

Status 200 Finalized staged artifacts available for the next task run
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",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task not found

Create tasks staged artifacts prepare upload

Reserve S3 object keys for task attachments before creating a new run and return presigned POST forms for direct uploads.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:id/staged_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/:id/staged_artifacts/prepare_upload/\
	-d artifacts="array"

Example response

Status 200 Prepared staged 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",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task not found

Create tasks staged artifacts prepare upload

Reserve S3 object keys for task attachments before creating a new run and return presigned POST forms for direct uploads.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:id/staged_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/:id/staged_artifacts/prepare_upload/\
	-d artifacts="array"

Example response

Status 200 Prepared staged 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",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task not found

Retrieve tasks usage

Return estimated model and cloud compute costs attributed to a task.

Required API key scopes

task:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:id/usage
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/:id/usage/

Example response

Status 200
RESPONSE
{
  "token_cost_usd": 0.1,
  "compute_cost_usd": 0.1,
  "total_cost_usd": 0.1
}

Retrieve tasks usage

Return estimated model and cloud compute costs attributed to a task.

Required API key scopes

task:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:id/usage
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/:id/usage/

Example response

Status 200
RESPONSE
{
  "token_cost_usd": 0.1,
  "compute_cost_usd": 0.1,
  "total_cost_usd": 0.1
}

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": {},
      "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"
    }
  ]
}

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
    arraynull
  • relayed_mcp_servers
    Click to open
    arraynull
  • environment
    Default: local
  • mode
    Default: background
  • branch
    stringnull
  • sandbox_environment_id
    string
  • custom_image_id
    string
  • pr_authorship_mode
  • auto_publish
    booleannull
  • run_source
  • signal_report_id
    string
  • runtime_adapter
  • model
    string
  • reasoning_effort
  • context_window
  • fast_mode
    booleannull
  • github_user_token
    string
  • initial_permission_mode
  • rtk_enabled
    booleannull

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","null"]

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": {},
  "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"
}
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 403 PostHog Desktop access is required, or Pi cloud runtime is disabled
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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "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"
}
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
  • state_append
    object
  • 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": "off",
  "log_url": "http://example.com",
  "error_message": "string",
  "output": {},
  "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"
}
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 analysis insight

Store one verified inefficiency finding on a task-analysis run. Only the run's own task-bound sandbox agent may call it, and only on a task-analysis run. The findings 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

  • no_findings_reason
  • observation
    string
  • evidence
    Click to open
    array
  • occurrence_count
    integer
  • category
  • other_justification
    string
  • wasted_effort
  • recurrence
  • confidence_basis
  • suggested_fix

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/analysis-insight
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-insight/\
	-d no_findings_reason=undefined

Example response

Status 201 Finding stored on the run
RESPONSE
{
  "insight_index": 0
}
Status 400 The finding is invalid, or the run already holds the maximum
Status 403 Only the run's own analysis sandbox may report findings
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
← Previous pageNext page →