Runs

Execute multi-step pipeline jobs in a single request with DAG dependencies and per-step status tracking.

Runs

Use Runs when you want to chain multiple Pi operations in one request and pass data between steps without managing intermediate state yourself. Pi executes steps in dependency order, handles retries, and surfaces per-step status.

Create a run

POST /api/v1/runs

Request

curl

curl -sS -X POST "$PI_BASE_URL/api/v1/runs" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      {
        "id": "extract_brand",
        "action": "brands.extract",
        "input": { "url": "https://example.com" }
      },
      {
        "id": "generate_hero",
        "action": "campaigns.generate",
        "depends_on": ["extract_brand"],
        "input": { "prompt": "Create a hero campaign ad for this brand" },
        "input_map": {
          "brand_id": "$steps.extract_brand.result.brand_id"
        }
      }
    ],
    "metadata": { "pipeline": "campaign-launch" }
  }'

Body parameters

steps · array · required

Ordered list of pipeline steps. Minimum 1, maximum 10.

Show step fields

steps[].id · string · required

Unique step identifier within this run. Referenced in depends_on and input_map expressions. Max 64 characters.

steps[].action · string · required

The Pi operation to execute. One of:

• "brands.extract" — extract brand identity from a URL
• "campaigns.generate" — generate a campaign ad
• "campaigns.edit" — edit an existing campaign ad
• "campaigns.localize_ad" — localize an ad for a target market

steps[].input · object

Input for this step. The accepted fields depend on the action. Defaults to {}.

steps[].depends_on · array

IDs of steps that must complete before this step starts. Defines the DAG execution order. Defaults to [].

steps[].input_map · object

Map prior step output into this step’s input. Keys are input field names; values are $steps.<step_id>.result.<field_path> expressions.

Common mappings:

• brand_id ← $steps.extract_brand.result.brand_id
• source_job_id ← $steps.generate_hero.result.job_id
• source_job_id ← $steps.edit_variant.result.job_id

metadata · object

Optional arbitrary metadata attached to the run record (e.g. pipeline name, user reference).

Response (202)

{
  "id": "req_pi_...",
  "object": "run",
  "status": "queued",
  "created_at": 1760000000,
  "data": {
    "run_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "status": "pending",
    "steps": [
      { "id": "extract_brand", "status": "pending" },
      { "id": "generate_hero", "status": "pending" }
    ]
  }
}

---

Retrieve a run

GET /api/v1/runs/:id

Path parameters

id · string · required

UUID of the run returned by POST /api/v1/runs.

Query parameters

wait_for_completion · boolean

Long-poll until the run reaches a terminal state or timeout_seconds elapses.

timeout_seconds · number

Long-poll timeout in seconds. Range: 1–30.

Request

curl

curl -X GET "$PI_BASE_URL/api/v1/runs/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee?wait_for_completion=true&timeout_seconds=30" \
  -H "Authorization: Bearer $PI_API_KEY"

Response fields

data.id · string

UUID of the run.

data.org_id · string

UUID of the owning organization.

data.status · string

Run-level status. One of "pending", "in_progress", "completed", "failed", "cancelled".

data.steps · array

Per-step results. Each item includes:

Show step result fields

id · string

Step identifier.

action · string

The action that was executed.

status · string

Step status. One of "pending", "queued", "processing", "completed", "failed", "skipped".

depends_on · array

IDs of steps this step waited for.

job_id · string | null

UUID of the underlying Pi job for this step.

result · object | null

Step output when status is "completed". Field names depend on the action type.

error · string | null

Error description when status is "failed".

started_at · integer | null

Unix timestamp when the step started executing.

completed_at · integer | null

Unix timestamp when the step reached a terminal state.

data.metadata · object | null

The metadata object provided at run creation.

data.created_at · integer

Unix timestamp when the run was created.

data.updated_at · integer

Unix timestamp of the most recent status change.

Three-step example: brand → ad → localization

{
  "steps": [
    {
      "id": "extract_brand",
      "action": "brands.extract",
      "input": { "url": "https://example.com" }
    },
    {
      "id": "generate_base",
      "action": "campaigns.generate",
      "depends_on": ["extract_brand"],
      "input": { "prompt": "Create a hero campaign ad" },
      "input_map": { "brand_id": "$steps.extract_brand.result.brand_id" }
    },
    {
      "id": "localize_fr",
      "action": "campaigns.localize_ad",
      "depends_on": ["generate_base"],
      "input": {
        "prompt": "Keep composition exactly",
        "target_culture": "French urban premium",
        "target_language": "fr",
        "target_currency": "EUR"
      },
      "input_map": { "source_job_id": "$steps.generate_base.result.job_id" }
    }
  ]
}