tasks
tasks

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

post/api/projects/{project_id}/tasks/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/tasks/
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Headers

X-PostHog-Client-Provenance'posthog_desktop' | 'posthog_mobile' | 'posthog_web'

First-party client creating the task. Accepted only with an interactive PostHog OAuth grant.

X-PostHog-Warm-Retrystring

Retry token from a warm_run_activation_unavailable response; prevents creating a replacement run.

Request body

titlestring

Short human-readable title. Auto-generated from description when omitted.

title_manually_setboolean

Whether the title was set by a human (vs auto-generated from the description).

descriptionstring

Free-form description of the work to be done. Used as the prompt passed to the agent.

origin_product'onboarding' | 'error_tracking' | 'eval_clusters' | 'user_created' | 'slack' | 'support_queue' | 'session_summaries' | 'posthog_ai' | 'experiments' | 'signal_report' | 'autoresearch' | 'signals_scout' | 'scout_suggestions' | 'support_reply' | 'hogdesk' | 'review_hog' | 'image_builder' | 'loop' | 'mcp_analytics' | 'signals_chat' | 'task_analysis' | 'workflow' | 'space_setup' | 'business_knowledge' | 'metrics_import'
  • onboarding - Onboarding
  • error_tracking - Error Tracking
  • eval_clusters - Eval Clusters
  • user_created - User Created
  • slack - Slack
  • support_queue - Support Queue
  • session_summaries - Session Summaries
  • posthog_ai - PostHog AI
  • experiments - Experiments
  • signal_report - Signal Report
  • autoresearch - Autoresearch
  • signals_scout - Signals Scout
  • scout_suggestions - Signals Scout Suggestions
  • support_reply - Support Reply
  • hogdesk - HogDesk
  • review_hog - ReviewHog
  • image_builder - Image Builder
  • loop - Loop
  • mcp_analytics - MCP Analytics
  • signals_chat - Signals Chat
  • task_analysis - Task Analysis
  • workflow - Workflow
  • space_setup - Space Setup
  • business_knowledge - Business Knowledge
  • metrics_import - Metrics Import
repositorystring nullable

Target GitHub repository in organization/repo format (e.g. posthog/posthog-js).

repositoriesstring[]

GitHub repositories available to this task, each in organization/repo format.

github_integrationinteger nullable

GitHub integration for this task.

github_user_integrationstring uuid nullable

User-scoped GitHub integration to use for user-authored cloud runs.

signal_reportstring uuid nullable

Signal report this task implements, when created from a report.

signal_report_task_relationshipstring

How the created task relates to the signal report (e.g. 'implementation', 'discussion'). Recorded as a signals task_run work-log entry; 'implementation' also opens the auto-start spend gate. Any routing-safe identifier (lowercase letters, numbers, '_', '-') is accepted except labels reserved for server-created tasks ('research', 'repo_selection', 'scout'). Non-implementation labels count toward the report's discussion task limit.

json_schemaunknown
archivedboolean

If true, the task is hidden from default list responses.

ci_promptstring nullable

Custom prompt for CI fixes. If blank, a default prompt will be used.

branchstring nullable

Base branch for the first run when start_run is true, or for matching a pre-warmed run. Omit to use the repository's default branch. Write-only and not persisted on the task.

modelstring nullable

LLM model for the first run when start_run is true, or for matching a pre-warmed run. Write-only.

pending_user_messagestring nullable

First user message when start_run is true or creation reuses a pre-warmed run. This message can differ from description. Ignored if creation does not start a run. Write-only and not persisted on the task.

pending_user_artifact_idsstring[]

Run artifact ids (already uploaded to the pre-warmed Run) to attach to the forwarded first message when creation reuses that warm Run, e.g. skill bundles or file attachments. If any id is missing from the warm Run's manifest, warm reuse is skipped and the task is created cold. Ignored when no warm Run is matched. Not supported when start_run is true.

auto_publishboolean nullable

When true, the agent pushes its work and opens a draft pull request on completion without an explicit request. Applies when start_run is true or creation reuses a pre-warmed run. Resumed runs keep this setting. Ignored if creation does not start a run. Write-only and not persisted on the task.

channelstring uuid nullable

Channel this task is owned by (the channel it was kicked off in).

scheduled_atstring nullable

Earliest start time for a one-off cloud run, in ISO 8601 format. Must be in the future and within 30 days. Times without an offset use UTC. Omit or send null to start immediately.

start_runboolean

Create the first cloud run. It starts immediately unless scheduled_at is set.

signal_report_discussion_questionstring

Question to forward to the signal report's scout when creating a discussion task. Send an empty string when there is no question. Omit only for older clients that embed the question in the task description. Not persisted on the task.

naming_sourcestring

Text the server generates the title from instead of description. Lets a client whose description is only an attachment summary (e.g. pasted text stored as a file) supply the real content for naming, so description (the prompt passed to the agent) stays unchanged. Not persisted.

sandbox_environment_idstring uuid nullable

Sandbox environment for the first run when start_run is true, or for matching a pre-warmed run. Not persisted on the task.

custom_image_idstring uuid nullable

Custom image for the first run when start_run is true, or for matching a pre-warmed run. Not persisted on the task.

runtime'acp' | 'pi'
  • acp - ACP
  • pi - Pi

Response

idstring uuid required
task_numberinteger nullable required
slugstring required
titlestring required
title_manually_setboolean required
descriptionstring required
origin_productstring required
runtime'acp' | 'pi' required
  • acp - ACP
  • pi - Pi
repositorystring nullable required
repositoriesstring[] required
github_integrationinteger nullable required
github_user_integrationstring uuid nullable required
signal_reportstring uuid nullable required
json_schemaobject nullable required
internalboolean required
archivedboolean required
archived_atstring date-time nullable required
created_atstring date-time nullable
updated_atstring date-time nullable
last_activity_atstring date-time nullable
ci_promptstring nullable required
channelstring uuid nullable
origin_keystring nullable

Stable key of the server-side flow that created this task, e.g. desktop_onboarding_session:<user_id>. Null for tasks people create themselves.

run_errorstring

Error returned when the task was created but its first run could not start.

Changes

No recorded changes to this operation across all 1 revision of this API.