task-runs
tasks
tasks

Create task run

Create a new run for a specific task without starting execution.

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

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/tasks/{task_id}/runs/
  • 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/.

task_idstring required

Request body

rtk_enabledboolean nullable

Whether rtk command-output compression is enabled for this run. Omitted or null follows the server-side default (enabled); false opts this run out.

benjamin_enabledboolean nullable

Whether the Benjamin-Plus token-efficiency instruction applies to this run. Omitted or null lets the server decide from the feature flag; true or false pins the choice for this run.

environment'local' | 'cloud'
  • local - local
  • cloud - cloud
mode'interactive' | 'background'
  • interactive - interactive
  • background - background
branchstring nullable

Git branch to checkout in the sandbox

sandbox_environment_idstring uuid

Optional sandbox environment to apply for this cloud run.

custom_image_idstring uuid

Optional custom base image for this cloud run's sandbox (Modal VM runtime only); takes precedence over the environment's image.

pr_authorship_mode'user' | 'bot'
  • user - user
  • bot - bot
auto_publishboolean nullable

When true, the cloud run agent pushes its work and opens a draft pull request on completion without waiting for an explicit ask.

run_source'manual' | 'signal_report'
  • manual - manual
  • signal_report - signal_report
signal_report_idstring

Optional signal report identifier when this run was started from Inbox.

runtime_adapter'claude' | 'codex'
  • claude - claude
  • codex - codex
modelstring

LLM model identifier to run in the selected runtime.

reasoning_effort'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultracode'
  • off - off
  • minimal - minimal
  • low - low
  • medium - medium
  • high - high
  • xhigh - xhigh
  • max - max
  • ultracode - ultracode
context_window'200k' | '1m'
  • 200k - 200k
  • 1m - 1m
fast_modeboolean nullable

Enable fast mode for models that support it.

github_user_tokenstring

Ephemeral GitHub user token from PostHog Desktop for user-authored cloud pull requests.

initial_permission_mode'default' | 'acceptEdits' | 'plan' | 'bypassPermissions' | 'auto' | 'read-only' | 'full-access'
  • default - default
  • acceptEdits - acceptEdits
  • plan - plan
  • bypassPermissions - bypassPermissions
  • auto - auto
  • read-only - read-only
  • full-access - full-access

Response

Created task run

idstring uuid required
taskstring uuid required

Parent task id this run belongs to.

stagestring nullable required
branchstring nullable required
statusstring required
environmentstring required
modelstring nullable

Configured LLM model identifier for this run.

log_urlstring uri nullable

Presigned S3 URL for log access (valid for 1 hour).

error_messagestring nullable required
outputobject nullable required
task_summarystring nullable required

Latest summary for this task, including a summary inherited from an earlier run.

task_tagsstring[] required

Latest slug tags for this task, including tags inherited from an earlier run.

stateobject required
created_atstring date-time nullable
updated_atstring date-time nullable
completed_atstring date-time nullable
scheduled_atstring date-time nullable

Earliest start time in UTC. Null for runs without a schedule.

preview_availableboolean

True when this run's sandbox serves a dev stack preview, so clients can offer the preview link. Open it through the run's preview/ endpoint, which mints a fresh access token on every request.

Changes

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