Tasks API Reference

Tasks

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

Endpoints

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

← Previous pageNext page →

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

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

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Request parameters

jsonrpc
method
params
object
id

Response

Example request

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

Status 400 Invalid command or no active sandbox

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

Status 404 Task run not found

Status 502 Agent server unreachable

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

Create tasks runs command

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

Status 400 Invalid command or no active sandbox

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

Status 404 Task run not found

Status 502 Agent server unreachable

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

Retrieve tasks runs connection token

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

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Response

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/connection_token
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/connection_token/
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 404 Task run not found

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 404 Task run not found

Retrieve tasks runs logs

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

Required API key scopes

task:read

Path parameters

id
string
task_id
string

Example request

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

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

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

Status 400 Run already active or workflow failed

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

Status 429 Team is over its posthog_code usage limit

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

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

Status 400 Run already active or workflow failed

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

Status 429 Team is over its posthog_code usage limit

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

Retrieve tasks runs session logs

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

Required API key scopes

task:read

Path parameters

id
string
task_id
string

Query parameters

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

Example request

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

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

Status 404 Run not found

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

Status 404 Run not found

Create tasks runs start

Start an existing cloud run after any initial run-scoped attachments have been uploaded.

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Request parameters

pending_user_message
string
pending_user_artifact_ids
array

Response

Example request

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

Example response

Status 200 Task with updated latest run

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "repository": "string",
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "ci_prompt": "string"
}

Status 400 Invalid start payload

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

Status 404 Task run not found

Status 429 Team is over its posthog_code usage limit

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

Create tasks runs start

Start an existing cloud run after any initial run-scoped attachments have been uploaded.

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Request parameters

pending_user_message
string
pending_user_artifact_ids
array

Response

Example request

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

Example response

Status 200 Task with updated latest run

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "repository": "string",
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "ci_prompt": "string"
}

Status 400 Invalid start payload

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

Status 404 Task run not found

Status 429 Team is over its posthog_code usage limit

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

Retrieve tasks runs stream

Server-Sent Events stream of task run events. Events carry an id: line (a Redis stream id) usable as a resume cursor.

The server caps each connection at 900 seconds: it emits event: end with data: {"type": "rotated"} and closes. This does NOT mean the run finished — reconnect with the Last-Event-ID header set to the last received event id to resume without gaps or duplicates. Only treat the stream as complete when the run itself reaches a terminal status.

?start=latest consumers must also carry Last-Event-ID across reconnects: reconnecting without it re-resolves to the then-current latest event, silently skipping anything published while disconnected.

SDK consumers: do not call the generated fetch wrapper for this path — it will buffer the entire stream. Use the URL builder (getTasksRunsStreamRetrieveUrl) with a streaming fetch/EventSource-style consumer and the Last-Event-ID header instead.

Required API key scopes

task:read

Path parameters

id
string
task_id
string

Query parameters

start
string

Example request

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

Retrieve tasks runs stream

Server-Sent Events stream of task run events. Events carry an id: line (a Redis stream id) usable as a resume cursor.

Required API key scopes

task:read

Path parameters

id
string
task_id
string

Query parameters

start
string

Example request

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

← Previous pageNext page →