Tasks

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

Endpoints

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

← Previous pageNext page →

List all tasks me config

Retrieve your per-project default AI run preferences, plus the resolved defaults a new run will use when no explicit runtime selection is sent (your preference over the project default).

Required API key scopes

task:read

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "ai_run_preferences": {
    "runtime": "acp",
    "runtime_adapter": "claude",
    "model": "string",
    "reasoning_effort": "off"
  },
  "resolved_ai_run_defaults": {
    "runtime": "string",
    "runtime_adapter": "string",
    "model": "string",
    "reasoning_effort": "string",
    "source": "user"
  },
  "agent_instructions": "string",
  "task_defaults": {
    "start_in_plan_mode": true,
    "auto_publish_cloud_runs": true,
    "default_cloud_target": "string"
  }
}

Create tasks me config

Set your per-project default AI run preferences; they override the project default wholesale. Send all fields as null to clear and inherit the project default.

Required API key scopes

task:write

Request parameters

runtime
runtime_adapter
model
string | null
reasoning_effort

Response

Example request

POST /api/projects/:project_id/tasks/@me/config
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/@me/config/\
	-d runtime=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/@me/config/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "ai_run_preferences": {
    "runtime": "acp",
    "runtime_adapter": "claude",
    "model": "string",
    "reasoning_effort": "off"
  },
  "resolved_ai_run_defaults": {
    "runtime": "string",
    "runtime_adapter": "string",
    "model": "string",
    "reasoning_effort": "string",
    "source": "user"
  },
  "agent_instructions": "string",
  "task_defaults": {
    "start_in_plan_mode": true,
    "auto_publish_cloud_runs": true,
    "default_cloud_target": "string"
  }
}

Create tasks me config agent instructions

Set your personal instructions, which PostHog cloud agents load in Tasks runs you start, after the project instructions. Autonomous runs never get them. Anyone who continues a task you started can see them, so leave out anything private. Send an empty string to clear.

Required API key scopes

task:write

Request parameters

agent_instructions
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "agent_instructions": "string"
}

Create tasks me config task defaults

Update your per-project defaults for new tasks. Fields you leave out keep their stored value.

Required API key scopes

task:write

Request parameters

start_in_plan_mode
boolean
auto_publish_cloud_runs
boolean
default_cloud_target
string | null

Response

Example request

POST /api/projects/:project_id/tasks/@me/config/task_defaults
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/@me/config/task_defaults/\
	-d start_in_plan_mode="boolean"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/@me/config/task_defaults/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"start_in_plan_mode": "boolean"
	}
).json()

Example response

Status 200

RESPONSE
{
  "start_in_plan_mode": true,
  "auto_publish_cloud_runs": true,
  "default_cloud_target": "string"
}

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.

List all tasks config

Retrieve the project-wide default AI run preferences for task runs.

Required API key scopes

task:read

Query parameters

limit
integer
offset
integer

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "ai_run_preferences": {
    "runtime": "acp",
    "runtime_adapter": "claude",
    "model": "string",
    "reasoning_effort": "off"
  },
  "agent_instructions": "string"
}

Create tasks config

Set the project-wide default AI run preferences applied to task runs created without an explicit runtime selection. Send all fields as null to clear.

Required API key scopes

task:write

Request parameters

runtime
runtime_adapter
model
string | null
reasoning_effort

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "ai_run_preferences": {
    "runtime": "acp",
    "runtime_adapter": "claude",
    "model": "string",
    "reasoning_effort": "off"
  },
  "agent_instructions": "string"
}

Create tasks config agent instructions

Set the project instructions that PostHog cloud agents load as their user-level AGENTS.md in every eligible Tasks run, including autonomous runs. Send an empty string to clear.

Required API key scopes

task:write

Request parameters

agent_instructions
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "agent_instructions": "string"
}

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"
      ],
      "cost_multiplier": "string"
    }
  ]
}

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"
      ],
      "cost_multiplier": "string"
    }
  ]
}

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

Create tasks pull request titles

Returns the GitHub titles of the pull requests that the latest run of each task opened.

Required API key scopes

task:read

Request parameters

ids
array

Response

Example request

POST /api/projects/:project_id/tasks/pull_request_titles
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/pull_request_titles/\
	-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/pull_request_titles/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "titles": {
    "property1": "string",
    "property2": "string"
  }
}

Create tasks pull request titles

Returns the GitHub titles of the pull requests that the latest run of each task opened.

Required API key scopes

task:read

Request parameters

ids
array

Response

Example request

POST /api/projects/:project_id/tasks/pull_request_titles
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/pull_request_titles/\
	-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/pull_request_titles/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "titles": {
    "property1": "string",
    "property2": "string"
  }
}

List all 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:read

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "rule_text": "string",
  "repository": "string",
  "priority": 0,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create tasks repo routing rules

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

Required API key scopes

task:write

Request parameters

rule_text
string
repository
string

Response

Example request

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

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "rule_text": "string",
  "repository": "string",
  "priority": 0,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve tasks repo routing rules

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

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "rule_text": "string",
  "repository": "string",
  "priority": 0,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Update tasks repo routing rules

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

Required API key scopes

task:write

Path parameters

id
string

Request parameters

rule_text
string
repository
string

Response

Example request

PATCH /api/projects/:project_id/tasks/repo_routing_rules/:id
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/repo_routing_rules/:id/\
	-d rule_text="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/tasks/repo_routing_rules/{tasks-7_id}/".format(
        project_id=project_id,
		tasks-7_id="<the tasks-7 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"rule_text": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "rule_text": "string",
  "repository": "string",
  "priority": 0,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

← Previous pageNext page →