Get Pipeline Runs
Recent pipeline_runs rows, newest first, with dataset owner info.
The table records both pipeline runs and — since SDK-399 — one row per
non-pipeline operation (search, recall, remember, forget,
delete, prune). Use the kind field to tell them apart:
"pipeline"— a pipeline run (pipeline_nameis set)."operation"— a single-row operation record (pipeline_nameandstatusare NULL, so these are invisible to status-based readers).
Request Parameters
- dataset_id (Optional[UUID]): Restrict to one dataset (403 if not readable).
- pipeline_name (Optional[str]): Exact-match filter; also excludes
operation records, which have no
pipeline_name. - limit (int): Page size, 1-500 (default: 50).
- offset (int): Rows to skip for pagination (default: 0).
Results are a bare JSON array, not a paged envelope. This endpoint has
always returned a top-level array, so wrapping it in a {"runs": [...], "total": N} envelope would break every existing caller — hence no
total. len(results) == limit means another page may exist.
Visibility
Without dataset_id: rows owned by the caller (and their child agents),
plus rows on any dataset shared with them. Operation records for
recall, prune, and multi-dataset search carry no dataset_id, so a
dataset-only filter would omit them entirely.
Response
A JSON array. Alongside the original id, pipeline_name, status,
dataset_id, dataset_name, owner_id, owner_email, created_at
and pipeline_run_id keys, each row carries the SDK-399 operation
columns. Every one of them is nullable: rows written before SDK-399
were not backfilled, and each writer sets only the subset it knows.
- kind (str):
"pipeline"or"operation"(never null). - operation_name (str|null): Operation name; for pipeline rows this
mirrors
pipeline_name, so it does not distinguish the two kinds. - origin (str|null): Initiating surface —
sdk/api/cli/mcp/background. - outcome (str|null):
"succeeded"/"failed". NULL on non-terminal rows. Read together withbackground: whenbackgroundis true, a"succeeded"outcome means the work was accepted and started, not that it finished. Treating those rows as completions inflates any success-rate or cost figure computed from this feed. - background (bool|null): True when the call launched background work. NULL means not applicable / not recorded.
- error_class (str|null): Exception class name when
outcome="failed". - tokens_in / tokens_out (int|null): Provider-billed token counts.
NULL means not measured;
0means measured zero — do not conflate. - started_at / ended_at (str|null): ISO-8601 timestamps.
- user_id (str|null): Triggering user.
- session_id (str|null): Session-cache id; joins
session_model_usage. - parent_operation_id (str|null): Parent’s
pipeline_run_id.
Aggregation caveats (append-only table)
Rows are append-only, so totals must not be summed naively:
- A pipeline run emits several rows sharing one
pipeline_run_id(initiated → started → terminal). Only the terminal row carriesoutcomeandtokens_*. Deduplicate bypipeline_run_idbefore summing, or you will multiply-count. parent_operation_idforms a tree whose token counts already chain into the parent. Summing across levels double-counts; sum one level.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Restrict the feed to a single dataset. When given, a missing read permission on that dataset is a 403 rather than an empty list.
Return only rows whose pipeline_name matches exactly. Operation records carry no pipeline_name, so this excludes them too — use it to stop a specific pipeline's history being crowded off the page by unrelated operation records.
Page size (max 500).
1 <= x <= 500Rows to skip for pagination.
x >= 0Response
Successful Response