Start here for 'what is broken' or 'why did last night's run fail'. Returns every failing and warning pipeline run in the window, already joined to the task runs that failed inside it, with each task's message, externalMessage, platformLink and duration-vs-baseline anomalies. Retried attempts are excluded. Windows wider than 168 hours are clamped to that, the widest the API serves. Follow up on a single task run with diagnose.

Deep dive on one failed task run: its status and messages, taskParameters and runParameters, the statuses of the upstream tasks it depends on, the tail of its newest log, and its artifact filenames. Task runs are queryable for 7 days only. Over-long parameter values, the log tail and the artifact list are capped, and the response says which parts were cut. Use download_task_run_log or download_task_run_artifact when the tail is not enough.

What an agent needs before editing or reasoning about a pipeline: its metadata, its full definition (the pipeline YAML structure as JSON), the integrations its tasks use, its recent run outcomes, and the median duration of its succeeded runs. Takes a pipeline ID or an alias. Run history covers the last 7 days, the widest window the API serves.

Build the URL of a pipeline run's lineage graph in the Orchestra UI.

Validate a full pipeline definition document without creating or updating a pipeline. Use it to check a definition before create_pipeline or update_pipeline.

Download a task run log file, returned base64-encoded. At most 3MiB of file content is returned per call; fetch larger files in chunks by passing range_header (e.g. 'bytes=0-3145727') and advancing the range each call.

Download a task run artifact file, returned base64-encoded. Artifacts such as a dbt manifest.json are often tens of MB. At most 3MiB of file content is returned per call; fetch larger files in chunks by passing range_header (e.g. 'bytes=0-3145727') and advancing the range each call.

Retrieve a paginated list of assets for the workspace the credential resolves to.

Assets can be filtered by type, integration, integration account, workspace, database, schema, status, or asset ID. By default, results are sorted by created_in_integration in descending order.

Retrieve a single asset by Orchestra asset ID or external ID.

List the audit trail for the workspace the credential resolves to, newest first: who did what, to which resource, and what changed.

occurred_after is required and sets how far back the trail is read; every other filter narrows within that window.

List the environments for the workspace the credential resolves to. Returns environment metadata only — fetch a single environment by ID to retrieve its variable values.

Create a new environment with an initial set of variable values. The first environment created for a workspace is automatically marked as the default.

Fetch a single environment by its ID, including its variable values.

Update an environment's name, default flag, and variable values. Only the fields supplied are changed; omitted fields are left untouched. The supplied values replace the existing values in full — they are not merged. Marking an environment as the default automatically unsets the previous default environment.

List incidents for the workspace the credential resolves to, most severe first, with merged children nested under their parent.

Filters apply to top-level incidents only - a child is always returned alongside its parent, so a filtered list still shows the full incident rather than part of one. Use name to filter incidents by a case-insensitive substring match on the incident name.

Fetch a single incident, with its merge relationships, summary counts and related resources.

Change an incident's status, severity or name. A field left out of the request body keeps its stored value. assignee is not settable via the public API yet.

Returns the detail shape - a patch writes timeline rows of its own, so the caller's event count is out of date the moment the change lands.

Fetch the timeline for a single incident, newest first. Paginated from the start - a grouped incident accumulates one event per attached failure, so the history runs to hundreds of rows well before anyone triages it.

Fetch the raw JSON an external system sent for one row of an incident's timeline - a row whose externalEventPath is set. Returns 410 once the payload has expired.

Merge the incidents named in the request body into the incident in the path. Merging is one level deep - merging an incident that already has a parent, or naming one that has incidents merged into it, is rejected rather than nesting further.

Detach the incidents named in the request body from the incident in the path, restoring each as a standalone incident. The exact inverse of merge.

Silence further alerts on this incident until the account's alert budget next refills. Already muted is a no-op.

Lift this incident's mute early. A no-op if it was never muted, or already lapsed.

Append a row to an incident's timeline, returning the event it wrote.

eventType says what the row records - COMMENT_ADDED (the default) for an ordinary comment, or AI_DIAGNOSIS_REQUESTED, AI_DIAGNOSIS_COMPLETED and AI_DIAGNOSIS_FAILED to record the start, result or failure of a diagnosis.

agentSessionId names the Orchestra agent session behind the write. The row is then attributed to Orchestra AI and linked to that session rather than to the API key; an agent takes the id from its ORCHESTRA_AGENT_SESSION_ID environment variable. The AI_DIAGNOSIS_* types require it. A session may write several over its life, but posting the same text twice returns the row already written.

description sets the incident's description alongside an AI_DIAGNOSIS_COMPLETED or AI_DIAGNOSIS_FAILED row, and needs edit permission on the incident. It is not applied over a description a person wrote.

The timeline is append-only: nothing can edit or delete a row once it is there.

List the integration connections configured for the workspace the credential resolves to. Returns connection metadata only — secret auth parameters are never included in the response. Optionally filter by integration or authStatus.

List the workspace's monitors in evaluation order. Where two monitors claim the same event, the one with the lower order wins.

Create a monitor: a rule for which failures to group into one incident, and how that incident alerts. match picks the events it claims, groupBy what makes two of them one incident, and action what happens to it - including mute, which claims the events and raises no incident or alert at all. Left out, order puts the new monitor last, so it only claims events no existing monitor claims.

Set the evaluation order of the workspace's monitors. monitorIds must name every monitor exactly once; each monitor's order becomes its position in the list.

Fetch a single monitor's definition.

Replace a monitor's definition with the one in the body. A field left out takes its default rather than keeping its stored value, except order, which keeps the monitor's place.

Retrieve a paginated list of task operations for the workspace the credential resolves to.

From 2026-10-01 the default changed from the last 7 days to the last 24 hours. Pass time_from and time_to explicitly to control the window.

Use operation filters to narrow results by operation type, integration, external ID, operation status, or task run ID.

Retrieve task runs belonging to a single pipeline run. This endpoint uses page_size default 10 and maximum 50.

List artifacts linked to a task run, such as dbt manifest.json, run_results.json, catalog.json, and sources.json files.

List log files linked to a task run. Use the returned filenames with the download endpoint.

Retrieve status details for a single pipeline run.

List pipeline runs with optional filters. status accepts comma-separated values: CREATED, RUNNING, SUCCEEDED, WARNING, FAILED, CANCELLING, CANCELLED.

Cancel a running pipeline run by its ID.

Fetch a single pipeline. Provide exactly one selector: pipeline_id, alias, or repository together with yaml_path.

List pipelines for the workspace the credential resolves to.

Always pass page and page_size to receive a paginated response with page, page_size, total, and results fields, sorted by pipeline name. Use name to filter pipelines by a case-insensitive substring match on the pipeline name.

Update an existing Orchestra-backed pipeline. Select it with pipeline_id or alias in the request body. Git-backed pipelines cannot be updated through this endpoint.

Create a new pipeline. The request body includes the pipeline definition as JSON.

Use Validate pipeline schema before creating a pipeline if you want to check the payload without saving it.

Fetch the full pipeline definition for a pipeline selected by pipeline_id or alias. Optionally specify a version, branch, or commit to load a specific revision.

Start a pipeline run. The pipeline can be identified by alias or pipeline ID.

All request body fields are optional. Use branch and commit for Git-backed pipelines, versionNumber for Orchestra-backed published versions, and runInputs for values required by pipeline inputs. The response includes a pipelineRunId you can use to poll run status.

Pause or unpause a pipeline by alias or pipeline ID. A paused pipeline's schedules, sensors, trigger events, and start_pipeline calls do not start new runs.

Migrate an Orchestra-backed pipeline to git-backed storage. Identify it with pipeline_id or alias, and omit working_branch when it equals default_branch.

Import a Git-backed pipeline definition from a repository into Orchestra.

Fetch the stored state for the given integration in the workspace the credential resolves to.

Retrieve a paginated list of task runs for the workspace the credential resolves to.

From 2026-10-01 the default changed from the last 7 days to the last 24 hours. Pass time_from and time_to explicitly to control the window.

Filter by multiple statuses, integrations, pipeline IDs, or task run IDs using comma-separated values. For example, status=SUCCEEDED,FAILED&integration=HTTP,SNOWFLAKE returns task runs matching either status and either integration.

Lists the workspaces this credential can act on. An API key is issued to one workspace, so it lists that workspace alone. An OAuth token lists the workspaces chosen when access was granted, limited to those its user is still a member of.

Pass a returned id to select the workspace on calls that act within one (the X-Orchestra-Account-Id header in the API).