Orchestrations

List orchestration runs

Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, by status, or by whether the run has a parent at all.

Note when aggregating: a run's usage covers its whole subtree, so summing it over a list that contains both a parent and its children counts the children more than once. Pass nested=false to sum over runs a caller started.

get/v1/projects/{project_id}/orchestration-runs

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/orchestration-runs
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Query parameters

orchestration_idstring

Filter by orchestration public ID (orch_...)

parent_orchestration_run_idstring

Filter to the runs one specific parent run's loop / sub_orchestration nodes started (run_...). This is how a caller holding a parent names the individual children behind its usage.

nestedboolean

Filter by whether the run was started by another run. false returns only the runs a caller started (no parent), which is the set to sum usage over; true returns only the runs a loop / sub_orchestration node started, across every parent. Omit to return both.

Contradicting parent_orchestration_run_id with nested=false is a 400; any value other than true or false is a 400.

statusstring[]

Filter by run status. Repeat the parameter to OR values — status=queued&status=running&status=sleeping&status=awaiting_input is the set still driving, which is how a caller finds live work without paging every run the project ever started.

There is no non_terminal shorthand on purpose: which statuses count as live is the caller's policy. A value outside the enum, empty string included, is a 400.

limitinteger

Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an integer it is 400.

offsetinteger

Results to skip. Negative or not an integer it is 400.

Response

List of runs

totalinteger required
limitinteger required
offsetinteger required

Example response

{
  "data": [
    {
      "orchestration_version": 3,
      "error": {
        "code": "AI_PROVIDER_ERROR",
        "message": "Provider returned 402: insufficient credits"
      },
      "metadata": {
        "author": "John",
        "revision": 2
      },
      "idempotency_key": "dispatch-2026-09-18-activation-42"
    }
  ]
}

Changes

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