Tasks API Reference

Tasks

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

Endpoints

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

← Previous pageNext page →

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

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 404 Run not found

Create tasks runs artifacts

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

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Request parameters

artifacts
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",
  "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",
  "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"
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/dismiss/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"artifact_ids": "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 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"
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/download/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"storage_path": "string"
	}
).json()

Example response

Status 200 Artifact content

Status 400 Invalid request

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 404 Artifact not found

Create tasks runs artifacts finalize upload

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

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Request parameters

artifacts
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"
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/finalize_upload/".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",
  "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
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"
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/prepare_upload/".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 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",
  "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"
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/presign/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"storage_path": "string"
	}
).json()

Example response

Status 200 Presigned URL for the requested artifact

RESPONSE
{
  "url": "http://example.com",
  "expires_in": 0
}

Status 400 Invalid request

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 404 Artifact not found

Create tasks runs 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
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"
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/references/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"references": "array"
	}
).json()

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
stringnull

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","null"]
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}/cancel/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"reason": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 200 Run already finished; 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": {},
  "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 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": {},
  "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 Run is not a cloud run

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 404 Task run not found

Status 503 Cancellation could not be delivered; safe to retry

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 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 checkpoints, 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/
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}/clear_conversation/".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 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": {},
  "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 Run not found

Status 409 Run is still active; send /clear to its agent

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

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
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}/command/".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 Agent server response

RESPONSE
{
  "jsonrpc": "string",
  "id": null,
  "result": null,
  "error": {}
}

Status 400 Invalid command or no active sandbox

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 403 PostHog Desktop access is required to message this run's agent

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 404 Task run not found

Status 429 Organization reached its PostHog Desktop 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
}

Status 502 Agent server unreachable

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Retrieve tasks runs connection token

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

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Response

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/connection_token
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/connection_token/
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}/connection_token/".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 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",
  "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",
  "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 and can find the most recent git_checkpoint event regardless of which run emitted it.

Required API key scopes

task:read

Path parameters

id
string
task_id
string

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/logs/
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}/logs/".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 Log content in JSONL format

Status 404 Task run not found

Retrieve tasks runs peers

Agent runs this run may send messages to: cloud Pi runs of tasks created by the same user, currently in progress or queued. Discovery and send validation share one visibility policy, so a run can only message what it can list; the per-entry sendable flag is the liveness contract.

Required API key scopes

task:read

Path parameters

id
string
task_id
string

Response

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/peers
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/peers/
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}/peers/".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 Active agent runs this run may message

RESPONSE
{
  "peers": [
    {
      "run_id": "string",
      "task_id": "string",
      "task_title": "string",
      "created_by_email": "string",
      "runtime": "string",
      "model": "string",
      "repository": "string",
      "stage": "string",
      "status": "string",
      "sendable": true,
      "updated_at": "string"
    }
  ]
}

Status 403 Peer messaging is disabled or the task is not on the Pi runtime

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 404 Run not found

Create tasks runs peers message

Relay a message from this run to a peer agent run. The body is delivered below a server-composed provenance envelope as a queued (non-steer) turn; attachments are copied into the target run's own artifact storage. accepted means queued for delivery, never delivered — the sandbox handoff happens later inside the target's workflow.

Required API key scopes

task:write

Path parameters

id
string
target_run_id
string
task_id
string

Request parameters

content
string
artifact_ids
array

Response

Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/peers/:target_run_id/message
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/peers/:target_run_id/message/\
	-d content="string"
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}/peers/{target_run_id}/message/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		target_run_id="<the target run id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"content": "string"
	}
).json()

Example response

Status 200 Synchronous send result (accepted / target_finished / rejected)

RESPONSE
{
  "result": "accepted",
  "detail": "string",
  "message_id": "string"
}

Status 400 Invalid message 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 Peer messaging is disabled or the task is not on the Pi runtime

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 404 Run not found

Create tasks runs relay message

Queue a Slack relay workflow to post a run message into the mapped Slack thread.

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Request parameters

text
string
message_id
stringnull
text_parts
array

Response

Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/relay_message
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/relay_message/\
	-d text="string"
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}/relay_message/".format(
        project_id=project_id,
		tasks-3_id="<the tasks-3 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"text": "string"
	}
).json()

Example response

Status 200 Relay accepted

RESPONSE
{
  "status": "string",
  "relay_id": "string"
}

Status 404 Run not found

Create tasks runs resume in cloud

Resume an existing task run in a cloud sandbox. Terminates any existing workflow and starts a new one.

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Response

Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/resume_in_cloud
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/resume_in_cloud/
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}/resume_in_cloud/".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 Run resumed in cloud

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "string",
  "environment": "string",
  "runtime_adapter": "claude",
  "provider": "anthropic",
  "model": "string",
  "reasoning_effort": "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 Run already active or workflow failed

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 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 session logs

Fetch session log entries for a task run with optional filtering by timestamp, event type, and limit.

Required API key scopes

task:read

Path parameters

id
string
task_id
string

Query parameters

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

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/session_logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/session_logs/
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}/session_logs/".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 Filtered log events as JSON array

Status 404 Task run not found

Update tasks runs set output

Update the output field for a task run (e.g., PR URL, commit SHA, etc.)

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Request parameters

output

Response

Example request

PATCH /api/projects/:project_id/tasks/:task_id/runs/:id/set_output
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/set_output/\
	-d output=undefined
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}/set_output/".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 Run with updated output

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "string",
  "environment": "string",
  "runtime_adapter": "claude",
  "provider": "anthropic",
  "model": "string",
  "reasoning_effort": "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 Run not found

← Previous pageNext page →