Tasks API Reference

Tasks

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

Endpoints

`POST`
`GET`
`GET`
`GET`
`POST`
`GET`
`POST`
`GET`
`POST`
`POST`
`GET`
`POST`
`DELETE`
`POST`
`GET`
`GET`
`GET`

← Previous pageNext page →

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-4_id}/start/".format(
        project_id=project_id,
		tasks-4_id="<the tasks-4 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",
  "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 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 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 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-4_id}/stream/".format(
        project_id=project_id,
		tasks-4_id="<the tasks-4 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

Retrieve tasks runs stream token

Generate a run-scoped JWT that authorizes reading this task run's live event stream via the agent-proxy.

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/stream_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/stream_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-4_id}/stream_token/".format(
        project_id=project_id,
		tasks-4_id="<the tasks-4 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Run-scoped token for reading the live event stream via the agent-proxy

RESPONSE
{
  "token": "string",
  "stream_base_url": "string"
}

Status 404 Task run not found

Retrieve tasks runs task session

API for managing task runs. Each run represents an execution of a 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/task_session
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/task_session/
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-4_id}/task_session/".format(
        project_id=project_id,
		tasks-4_id="<the tasks-4 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "download_url": "http://example.com",
  "content_sha256": "string"
}

Status 404 Task session not found

Create tasks runs task session sync

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

Response

Example request

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "content_sha256": "string"
}

Status 400 Missing required header

Status 403 Invalid task run token

Status 404 Task session not found

Status 409

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

List all tasks runs living artifacts

Returns stable, versioned artifact handles created by the run's task.

Required API key scopes

task:read

Path parameters

run_id
string
task_id
string

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:run_id/living_artifacts
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/:run_id/living_artifacts/
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/{run_id}/living_artifacts/".format(
        project_id=project_id,
		run_id="<the run id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Living artifacts registered for this task run

RESPONSE
{
  "artifacts": [
    {
      "id": "string",
      "task_id": "string",
      "run_id": "string",
      "team_id": 0,
      "name": "string",
      "artifact_type": "slack_message",
      "adapter": "slack_message",
      "status": "active",
      "location": null,
      "metadata": null,
      "current_version": 0,
      "versions": [
        {}
      ],
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}

Status 404 Run not found

Create tasks runs living artifacts

Create a stable, editable artifact handle from direct markdown/text content or an existing run artifact. Slack adapters deliver into the mapped Slack thread; document artifacts use external connector storage when available.

Required API key scopes

task:write

Path parameters

run_id
string
task_id
string

Request parameters

name
string
artifact_type
Default: document
adapter
content
string
content_base64
string
content_type
string
source_artifact_id
string
source_storage_path
string
metadata
object

Response

Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:run_id/living_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/:run_id/living_artifacts/\
	-d name="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/{run_id}/living_artifacts/".format(
        project_id=project_id,
		run_id="<the run id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 Created living artifact

RESPONSE
{
  "id": "string",
  "task_id": "string",
  "run_id": "string",
  "team_id": 0,
  "name": "string",
  "artifact_type": "slack_message",
  "adapter": "slack_message",
  "status": "active",
  "location": null,
  "metadata": null,
  "current_version": 0,
  "versions": [
    {}
  ],
  "created_at": "string",
  "updated_at": "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

Retrieve tasks runs living artifacts

Return a stable living artifact handle and the current content when the adapter supports reads.

Required API key scopes

task:read

Path parameters

id
string
run_id
string
task_id
string

Response

Example request

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

Example response

Status 200 Living artifact with current readable content

RESPONSE
{
  "id": "string",
  "task_id": "string",
  "run_id": "string",
  "team_id": 0,
  "name": "string",
  "artifact_type": "slack_message",
  "adapter": "slack_message",
  "status": "active",
  "location": null,
  "metadata": null,
  "current_version": 0,
  "versions": [
    {}
  ],
  "created_at": "string",
  "updated_at": "string",
  "content": "string"
}

Status 404 Living artifact not found

Create tasks runs living artifacts

Commit a new version to an existing living artifact handle.

Required API key scopes

task:write

Path parameters

id
string
run_id
string
task_id
string

Request parameters

name
string
content
string
content_base64
string
content_type
string
source_artifact_id
string
source_storage_path
string
metadata
object

Response

Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:run_id/living_artifacts/:id/edit
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/:run_id/living_artifacts/:id/edit/\
	-d name="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/{run_id}/living_artifacts/{tasks-4_id}/edit/".format(
        project_id=project_id,
		tasks-4_id="<the tasks-4 id>",
		run_id="<the run id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 Updated living artifact

RESPONSE
{
  "id": "string",
  "task_id": "string",
  "run_id": "string",
  "team_id": 0,
  "name": "string",
  "artifact_type": "slack_message",
  "adapter": "slack_message",
  "status": "active",
  "location": null,
  "metadata": null,
  "current_version": 0,
  "versions": [
    {}
  ],
  "created_at": "string",
  "updated_at": "string"
}

Status 400 Invalid artifact update

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 Living artifact not found

Create tasks runs living artifacts

Renders a PostHog insight (ad-hoc query JSON or a saved insight) to a PNG server-side and registers it as a slack_file living artifact in one call. Blocks until the render finishes.

Required API key scopes

task:writequery:read

Path parameters

run_id
string
task_id
string

Request parameters

name
string
query
object
insight_id
integer

Response

Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:run_id/living_artifacts/chart
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/:run_id/living_artifacts/chart/\
	-d name="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/{run_id}/living_artifacts/chart/".format(
        project_id=project_id,
		run_id="<the run id>",,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 Chart rendered and registered as a living artifact

RESPONSE
{
  "artifact": {
    "id": "string",
    "task_id": "string",
    "run_id": "string",
    "team_id": 0,
    "name": "string",
    "artifact_type": "slack_message",
    "adapter": "slack_message",
    "status": "active",
    "location": null,
    "metadata": null,
    "current_version": 0,
    "versions": [
      {}
    ],
    "created_at": "string",
    "updated_at": "string"
  },
  "export_asset_id": 0,
  "url": "http://example.com"
}

Status 400 Render or delivery 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 Caller may not run queries in this project

Status 404 Run not found

List all tasks thread messages

The task's thread in chronological order.

Required API key scopes

task:read

Path parameters

task_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

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

Example response

Status 200 Thread messages

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",
      "author_kind": "string",
      "event": "string",
      "payload": {},
      "content": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "author": {
        "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"
      },
      "forwarded_to_agent_at": "2019-08-24T14:15:22Z",
      "forwarded_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"
      }
    }
  ]
}

Create tasks thread messages

API for a task's thread — the human-only side conversation around a task. Messages reach the agent only via the explicit send_to_agent action, gated to the task author.

Required API key scopes

task:write

Path parameters

task_id
string

Request parameters

content
string

Response

Example request

POST /api/projects/:project_id/tasks/:task_id/thread_messages
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/thread_messages/\
	-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}/thread_messages/".format(
        project_id=project_id,
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"content": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "author_kind": "string",
  "event": "string",
  "payload": {},
  "content": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "author": {
    "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"
  },
  "forwarded_to_agent_at": "2019-08-24T14:15:22Z",
  "forwarded_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"
  }
}

Delete tasks thread messages

API for a task's thread — the human-only side conversation around a task. Messages reach the agent only via the explicit send_to_agent action, gated to the task author.

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Example request

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

Example response

Status 204 No response body

Create tasks thread messages send to agent

Task author only: forwards the message into the task's latest live run.

Required API key scopes

task:write

Path parameters

id
string
task_id
string

Request parameters

id
string
task
string
author_kind
string
event
string
payload
object
content
string
created_at
string
author
forwarded_to_agent_at
stringnull
forwarded_by

Response

Example request

POST /api/projects/:project_id/tasks/:task_id/thread_messages/:id/send_to_agent
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/thread_messages/:id/send_to_agent/\
	-d id="string",\
	-d task="string",\
	-d author_kind="string",\
	-d event="string",\
	-d payload="object",\
	-d content="string",\
	-d created_at="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}/thread_messages/{tasks-4_id}/send_to_agent/".format(
        project_id=project_id,
		tasks-4_id="<the tasks-4 id>",
		task_id="<the task id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"id": "string",
		"task": "string",
		"author_kind": "string",
		"event": "string",
		"payload": "object",
		"content": "string",
		"created_at": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "author_kind": "string",
  "event": "string",
  "payload": {},
  "content": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "author": {
    "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"
  },
  "forwarded_to_agent_at": "2019-08-24T14:15:22Z",
  "forwarded_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"
  }
}

Status 400 No signalable run, or message already forwarded

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 active wizard run

Returns the most recent onboarding wizard cloud run for the current project when it is still running (or completed within the last day), so the setup-progress FAB can rehydrate after a drop-flow signup that started the run server-side. Returns 204 when there is none.

Required API key scopes

task:read

Response

Example request

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

Example response

Status 200 The team's active onboarding wizard cloud run.

RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "status": "string",
  "started_at": "2019-08-24T14:15:22Z"
}

Status 204 No active onboarding wizard cloud run for this project.

Retrieve tasks active wizard run

Required API key scopes

task:read

Response

Example request

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

Example response

Status 200 The team's active onboarding wizard cloud run.

RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "status": "string",
  "started_at": "2019-08-24T14:15:22Z"
}

Status 204 No active onboarding wizard cloud run for this project.

Retrieve tasks models

Return the models a task run may use, with the reasoning efforts each one supports. Derived from the live LLM gateway catalogue, so a newly released model appears without a client change. An empty list means the gateway is unreachable — clients should fall back to their own default rather than treating it as 'no models exist'.

Required API key scopes

task:read

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "models": [
    {
      "runtime_adapter": "claude",
      "model": "string",
      "display_name": "string",
      "supported_efforts": [
        "low"
      ]
    }
  ]
}

Retrieve tasks models

Required API key scopes

task:read

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "models": [
    {
      "runtime_adapter": "claude",
      "model": "string",
      "display_name": "string",
      "supported_efforts": [
        "low"
      ]
    }
  ]
}

Retrieve tasks pinned

Return the visible tasks pinned by the requester in the current project.

Required API key scopes

task:read

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "task_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Retrieve tasks pinned

Return the visible tasks pinned by the requester in the current project.

Required API key scopes

task:read

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "task_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

← Previous pageNext page →