Tasks API Reference

Tasks

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

Endpoints

`GET`
`GET`
`GET`
`GET`
`POST`
`POST`

← Previous page

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

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

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

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

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 search

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

Required API key scopes

task:read

Query parameters

limit
integer
Default: 20
q
string

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "kind": "task",
  "title": "string",
  "subtitle": "string",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  "metadata": null
}

Retrieve tasks search

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

Required API key scopes

task:read

Query parameters

limit
integer
Default: 20
q
string

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "kind": "task",
  "title": "string",
  "subtitle": "string",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  "metadata": null
}

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

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"
  },
  "task": {
    "id": "string",
    "team_id": 0,
    "title": "string",
    "repository": "string",
    "origin_product": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "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"
      }
    }
  ]
}

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

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"
  },
  "task": {
    "id": "string",
    "team_id": 0,
    "title": "string",
    "repository": "string",
    "origin_product": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "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"
      }
    }
  ]
}

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

Create tasks summaries

Returns summary for the requested tasks: id, title, repository, created_at, updated_at, and the latest run's 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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/summaries/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array"
	}
).json()

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_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "origin_product": "string",
      "latest_run": {
        "status": "not_started",
        "environment": "local"
      }
    }
  ]
}

Create tasks summaries

Returns summary for the requested tasks: id, title, repository, created_at, updated_at, and the latest run's 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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/summaries/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array"
	}
).json()

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_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "origin_product": "string",
      "latest_run": {
        "status": "not_started",
        "environment": "local"
      }
    }
  ]
}

Create tasks warm

Warm a full idling Run for a Code-app 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
stringnull
repositories
array
github_integration
integernull
branch
stringnull
runtime_adapter
model
stringnull
reasoning_effort
sandbox_environment_id
stringnull
custom_image_id
stringnull

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

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",
  "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 warm

Required API key scopes

task:write

Request parameters

repository
stringnull
repositories
array
github_integration
integernull
branch
stringnull
runtime_adapter
model
stringnull
reasoning_effort
sandbox_environment_id
stringnull
custom_image_id
stringnull

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

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",
  "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
}

← Previous page