Tasks

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

Endpoints

DELETE
GET
GET
GET
GET
GET
POST
POST

Delete tasks repo routing rules

Team routing rules that steer agent repo selection (RepoRoutingRule).

The same rows the Slack /posthog rules commands manage; the repo selection agent reads them ordered by priority when picking a repository for a task. Rules whose repository is not connected to the project are ignored at selection time, so a stale rule is inert rather than harmful — which is why writes here don't check the connected-repository list (the UI constrains the picker to connected repos anyway).

Required API key scopes

task:write

Path parameters

  • id
    string

Example request

DELETE /api/projects/:project_id/tasks/repo_routing_rules/: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/repo_routing_rules/:id/

Example response

Status 204 No response body

Retrieve tasks repositories

Return the set of repositories referenced by non-deleted, non-internal tasks in the current project. Used to populate repository filter pickers without being constrained by task list pagination.

Required API key scopes

task:read

Response


Example request

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

Example response

Status 200 Distinct repositories used by tasks in the current project.
RESPONSE
{
"repositories": [
"string"
]
}

Retrieve tasks repositories

Return the set of repositories referenced by non-deleted, non-internal tasks in the current project. Used to populate repository filter pickers without being constrained by task list pagination.

Required API key scopes

task:read

Response


Example request

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

Example response

Status 200 Distinct repositories used by tasks in the current project.
RESPONSE
{
"repositories": [
"string"
]
}

Retrieve tasks repository readiness

Get autonomy readiness details for a specific repository in the current project.

Required API key scopes

task:read

Query parameters

  • refresh
    boolean
    Default: false
  • repository
    string
  • window_days
    integer
    Default: 7

Response


Example request

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

Example response

Status 200 Repository readiness status
RESPONSE
{
"repository": "string",
"classification": "string",
"excluded": true,
"coreSuggestions": {
"state": "needs_setup",
"estimated": true,
"reason": "string",
"evidence": {}
},
"replayInsights": {
"state": "needs_setup",
"estimated": true,
"reason": "string",
"evidence": {}
},
"errorInsights": {
"state": "needs_setup",
"estimated": true,
"reason": "string",
"evidence": {}
},
"overall": "string",
"evidenceTaskCount": 0,
"windowDays": 0,
"generatedAt": "string",
"cacheAgeSeconds": 0,
"scan": {
"filesScanned": 0,
"detectedFilesCount": 0,
"eventNameCount": 0,
"foundPosthogInit": true,
"foundPosthogCapture": true,
"foundErrorSignal": true
}
}

Retrieve tasks repository readiness

Get autonomy readiness details for a specific repository in the current project.

Required API key scopes

task:read

Query parameters

  • refresh
    boolean
    Default: false
  • repository
    string
  • window_days
    integer
    Default: 7

Response


Example request

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

Example response

Status 200 Repository readiness status
RESPONSE
{
"repository": "string",
"classification": "string",
"excluded": true,
"coreSuggestions": {
"state": "needs_setup",
"estimated": true,
"reason": "string",
"evidence": {}
},
"replayInsights": {
"state": "needs_setup",
"estimated": true,
"reason": "string",
"evidence": {}
},
"errorInsights": {
"state": "needs_setup",
"estimated": true,
"reason": "string",
"evidence": {}
},
"overall": "string",
"evidenceTaskCount": 0,
"windowDays": 0,
"generatedAt": "string",
"cacheAgeSeconds": 0,
"scan": {
"filesScanned": 0,
"detectedFilesCount": 0,
"eventNameCount": 0,
"foundPosthogInit": true,
"foundPosthogCapture": true,
"foundErrorSignal": true
}
}



Retrieve tasks slack thread context

PostHog-internal debug tool. Resolves a Slack permalink to the linked task, its runs, the task-processing and mention-dispatch Temporal workflow ids/URLs, and presigned log URLs.

Required API key scopes

task:read

Query parameters

  • url
    string

Response


Example request

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

Example response

Status 200 Task, runs, and Temporal workflow handles for the Slack thread.
RESPONSE
{
"thread": {
"url": "string",
"channel": "string",
"thread_ts": "string",
"slack_workspace_id": "string",
"mentioning_slack_user_id": "string",
"queue_workflow_id": "string",
"queue_workflow_url": "string",
"mapping_admin_url": "string"
},
"task": {
"id": "string",
"team_id": 0,
"title": "string",
"repository": "string",
"origin_product": "string",
"created_at": "2019-08-24T14:15:22Z",
"url": "string",
"admin_url": "string"
},
"runs": [
{
"id": "string",
"status": "string",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"sandbox_url": "string",
"pr_url": "string",
"error_message": "string",
"task_processing_workflow_id": "string",
"task_processing_workflow_url": "string",
"mention_workflow_id": "string",
"mention_workflow_url": "string",
"task_view_url": "string",
"log_url": "string",
"repo_research": {
"task_id": "string",
"run_id": "string",
"status": "string",
"task_processing_workflow_id": "string",
"task_processing_workflow_url": "string",
"sandbox_url": "string",
"task_view_url": "string",
"log_url": "string"
},
"admin_url": "string"
}
]
}
Status 400 Malformed Slack URL or unparseable thread identifiers.
Status 403 Endpoint is gated to PostHog-internal debugging.
Status 404 No SlackThreadTaskMapping exists for the parsed (channel, thread_ts).

Retrieve tasks slack thread context

PostHog-internal debug tool. Resolves a Slack permalink to the linked task, its runs, the task-processing and mention-dispatch Temporal workflow ids/URLs, and presigned log URLs.

Required API key scopes

task:read

Query parameters

  • url
    string

Response


Example request

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

Example response

Status 200 Task, runs, and Temporal workflow handles for the Slack thread.
RESPONSE
{
"thread": {
"url": "string",
"channel": "string",
"thread_ts": "string",
"slack_workspace_id": "string",
"mentioning_slack_user_id": "string",
"queue_workflow_id": "string",
"queue_workflow_url": "string",
"mapping_admin_url": "string"
},
"task": {
"id": "string",
"team_id": 0,
"title": "string",
"repository": "string",
"origin_product": "string",
"created_at": "2019-08-24T14:15:22Z",
"url": "string",
"admin_url": "string"
},
"runs": [
{
"id": "string",
"status": "string",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"sandbox_url": "string",
"pr_url": "string",
"error_message": "string",
"task_processing_workflow_id": "string",
"task_processing_workflow_url": "string",
"mention_workflow_id": "string",
"mention_workflow_url": "string",
"task_view_url": "string",
"log_url": "string",
"repo_research": {
"task_id": "string",
"run_id": "string",
"status": "string",
"task_processing_workflow_id": "string",
"task_processing_workflow_url": "string",
"sandbox_url": "string",
"task_view_url": "string",
"log_url": "string"
},
"admin_url": "string"
}
]
}
Status 400 Malformed Slack URL or unparseable thread identifiers.
Status 403 Endpoint is gated to PostHog-internal debugging.
Status 404 No SlackThreadTaskMapping exists for the parsed (channel, thread_ts).

Retrieve tasks sources

Return the distinct sources of the requester's own non-archived tasks, in the words of the task list sources filter. Used to populate a source filter picker without being constrained by task list pagination.

Required API key scopes

task:read

Response


Example request

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

Example response

Status 200
RESPONSE
{
"sources": [
"autoresearch"
]
}

Retrieve tasks sources

Return the distinct sources of the requester's own non-archived tasks, in the words of the task list sources filter. Used to populate a source filter picker without being constrained by task list pagination.

Required API key scopes

task:read

Response


Example request

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

Example response

Status 200
RESPONSE
{
"sources": [
"autoresearch"
]
}

Create tasks summaries

Returns summary for the requested tasks, including the creator ID and the latest run's ID, status, and environment.

Required API key scopes

task:read

Query parameters

  • limit
    integer
  • offset
    integer

Request parameters

  • ids
    array

Response


Example request

POST /api/projects/:project_id/tasks/summaries
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/summaries/\
-d ids="array"

Example response

Status 200 Summary fields for the requested tasks
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",
"title": "string",
"repository": "string",
"created_by_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"origin_product": "string",
"latest_run": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "not_started",
"environment": "local",
"mode": "interactive",
"pr_url": "string",
"pr_state": "open",
"task_summary": "string"
}
}
]
}

Create tasks summaries

Returns summary for the requested tasks, including the creator ID and the latest run's ID, status, and environment.

Required API key scopes

task:read

Query parameters

  • limit
    integer
  • offset
    integer

Request parameters

  • ids
    array

Response


Example request

POST /api/projects/:project_id/tasks/summaries
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/summaries/\
-d ids="array"

Example response

Status 200 Summary fields for the requested tasks
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",
"title": "string",
"repository": "string",
"created_by_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"origin_product": "string",
"latest_run": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "not_started",
"environment": "local",
"mode": "interactive",
"pr_url": "string",
"pr_state": "open",
"task_summary": "string"
}
}
]
}

Create tasks warm

Warm a full idling Run for a cloud task while the user composes: boot a sandbox, clone the repo, check out the branch, and start the agent, then idle awaiting the first message. On submit the normal create+run path transparently reuses and activates this Run; abandoned warms are reaped by the Run's inactivity timeout. Best-effort: returns an empty body when the feature flag is off, the warm pool is full, or the GitHub integration doesn't belong to the team.

Required API key scopes

task:write

Request parameters

  • repository
    string | null
  • repositories
    array
  • github_integration
    integer | null
  • branch
    string | null
  • runtime_adapter
  • model
    string | null
  • reasoning_effort
  • sandbox_environment_id
    string | null
  • custom_image_id
    string | null
  • origin_product
    Default: user_created
  • initial_permission_mode
  • signal_report
    string | null

Response


Example request

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

Example response

Status 200 Warm Run provisioned (`task_id`/`run_id` to activate on submit), or an empty body when the feature is off, capped, or the integration didn't resolve.
RESPONSE
{
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec"
}
Status 403 PostHog Desktop access is required
RESPONSE
{
"detail": "string",
"error": "string",
"type": "string",
"code": "string",
"retry_token": "string",
"reason": "startup_plan",
"attr": "string",
"missing_artifact_ids": [
"string"
],
"limit_type": "burst",
"reset_at": "string",
"is_pro": true
}
Status 429 Team is over its posthog_code usage limit
RESPONSE
{
"detail": "string",
"error": "string",
"type": "string",
"code": "string",
"retry_token": "string",
"reason": "startup_plan",
"attr": "string",
"missing_artifact_ids": [
"string"
],
"limit_type": "burst",
"reset_at": "string",
"is_pro": true
}
Status 503 PostHog Desktop access could not be verified
RESPONSE
{
"detail": "string",
"error": "string",
"type": "string",
"code": "string",
"retry_token": "string",
"reason": "startup_plan",
"attr": "string",
"missing_artifact_ids": [
"string"
],
"limit_type": "burst",
"reset_at": "string",
"is_pro": true
}

Create tasks warm

Warm a full idling Run for a cloud task while the user composes: boot a sandbox, clone the repo, check out the branch, and start the agent, then idle awaiting the first message. On submit the normal create+run path transparently reuses and activates this Run; abandoned warms are reaped by the Run's inactivity timeout. Best-effort: returns an empty body when the feature flag is off, the warm pool is full, or the GitHub integration doesn't belong to the team.

Required API key scopes

task:write

Request parameters

  • repository
    string | null
  • repositories
    array
  • github_integration
    integer | null
  • branch
    string | null
  • runtime_adapter
  • model
    string | null
  • reasoning_effort
  • sandbox_environment_id
    string | null
  • custom_image_id
    string | null
  • origin_product
    Default: user_created
  • initial_permission_mode
  • signal_report
    string | null

Response


Example request

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

Example response

Status 200 Warm Run provisioned (`task_id`/`run_id` to activate on submit), or an empty body when the feature is off, capped, or the integration didn't resolve.
RESPONSE
{
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec"
}
Status 403 PostHog Desktop access is required
RESPONSE
{
"detail": "string",
"error": "string",
"type": "string",
"code": "string",
"retry_token": "string",
"reason": "startup_plan",
"attr": "string",
"missing_artifact_ids": [
"string"
],
"limit_type": "burst",
"reset_at": "string",
"is_pro": true
}
Status 429 Team is over its posthog_code usage limit
RESPONSE
{
"detail": "string",
"error": "string",
"type": "string",
"code": "string",
"retry_token": "string",
"reason": "startup_plan",
"attr": "string",
"missing_artifact_ids": [
"string"
],
"limit_type": "burst",
"reset_at": "string",
"is_pro": true
}
Status 503 PostHog Desktop access could not be verified
RESPONSE
{
"detail": "string",
"error": "string",
"type": "string",
"code": "string",
"retry_token": "string",
"reason": "startup_plan",
"attr": "string",
"missing_artifact_ids": [
"string"
],
"limit_type": "burst",
"reset_at": "string",
"is_pro": true
}