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. 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.

Delete an environment entirely. The default environment cannot be deleted while other environments still exist. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.

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.

Get the workspace's incident settings: whether incidents are on, which failures can raise one, and how incidents alert. A workspace that has never saved its settings gets the defaults.

Change the workspace's incident settings and return all of them. Settings left out of the body keep their current value.

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. Use sort_column and sort_direction to sort top-level incidents by a single column instead; merged children keep the default order.

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

Change an incident's status, severity, name, assignee or subscribers. A field left out of the request body keeps its stored value, and sending assignee as null unassigns. An assignee or subscriber must be able to view the incident or be in the account's Slack workspace.

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 hasExternalEvent is true. 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.

agentSessionId is optional, and only Orchestra agent sessions should set it. When set, the merge is attributed to Orchestra AI and linked to that session, and the session may only merge the incident it was started for, into an older incident.

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.

Fetch a single integration connection in the workspace the credential resolves to, including its auth parameters. Secret auth parameters are obfuscated in the response.

Delete an integration connection from the workspace the credential resolves to, along with any agent integration mappings that use it. The default connection cannot be deleted while the integration has other connections. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.

Update one of connectionName, isDefault: true, or parameters with credentialStore on an integration connection. parameters follow the integration's authSchema and re-authenticate the connection; send obfuscated secrets back unchanged to keep them. OAuth integrations return a redirectUrl instead.

Create a connection for an integration in the caller's workspace. parameters must match the integration's authSchema, as returned by Get an integration. Secret parameters are obfuscated in the response. OAuth integrations return a redirectUrl instead and need a user's credential.

Fetch a single integration by its identifier, including its auth and job schemas. Each auth_schema item's name is a connection field, and format: password marks a secret one.

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.

Delete a monitor. Incidents it already claimed keep their link to it; new events fall through to the next matching monitor or the built-in grouping rules. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.

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, semantic_manifest.json, and sources.json files. For dbt v2, dbt docs generate produces index.html, assets.zip, and info_schema.zip instead of catalog.json.

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

Retrieve a single pipeline run by ID, including its status, however long ago it ran.

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

Cancel a running or queued 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.

Delete a pipeline. Provide exactly one selector: pipeline_id, alias, or repository together with yaml_path. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.

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.

Any other JSON body, such as a webhook sent by another tool, still starts the run, with default options; requestBodyMessage and requestBodyErrors in the response say which happened. Either way the whole body is available to the pipeline's webhook.runInputs as ${{ outputs.payload }}, for example ${{ outputs.payload.connection_id }}, or ${{ outputs.payload['connectionId'] }} for a key with capitals, so task conditions can act on it through ${{ inputs.<name> }}. Bodies over 64 KiB are not kept.

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.

Move an Orchestra-backed pipeline to a folder by alias or pipeline ID, leaving its definition and versions as they are. A git-backed pipeline's folder comes from where its YAML file lives, so move the file instead.

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.

Retrieve a single task run by ID, however long ago it ran, without needing its pipeline run ID.

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).

List the avatars an agent can use: Orchestra's stock avatars and those uploaded to the workspace the credential resolves to. Pass an entry's path as avatar_path when creating or updating an agent. url is a short-lived link to the image, and is omitted for an uploaded avatar that is still being scanned for malware.

List the agents in the workspace the credential resolves to, including those managed by Orchestra, filtered to the agents the caller may view. Prompts and secrets are not included; get an agent by id for those.

Create an agent in the workspace the credential resolves to. Prompts are Markdown, avatarPath is a path from the avatar catalog, gitEnabled needs the workspace's git connection, and llmKeyType picks whose LLM key its sessions use. Secrets are returned masked.

Get an agent with its prompts and settings. Secrets are returned masked. Returns 404 if the agent does not exist in the workspace the credential resolves to.

Delete an agent from the workspace the credential resolves to. Agents managed by Orchestra cannot be deleted, and are refused with 403. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.

Update the fields given and leave the rest unchanged; send null to clear an optional field. A masked secret value keeps the stored secret. An agent managed by Orchestra accepts only gitEnabled, secrets and llmKeyType, which apply to this workspace alone, and refuses any other field with 403.

List the skills attached to an agent, with each skill's name and description. Returns 404 if the agent does not exist in the workspace the credential resolves to.

Replace the skills attached to an agent with the given list: skills not in the list are detached, and an empty list detaches them all. Each skillId must be a skill in the same workspace or one managed by Orchestra, and the request is refused with 404 if any is not; duplicates are ignored. Agents managed by Orchestra cannot have their skills changed.

List the integration connections an agent can use. Each integration is a connection key of the form <INTEGRATION>_<connection id>, e.g. SNOWFLAKE_my_connection. Returns 404 if the agent does not exist in the workspace the credential resolves to.

Replace the integration connections an agent can use with the given list, and return the agent's integrations afterwards. An empty list removes them all. Each integration is a connection key of the form <INTEGRATION>_<connection id>, e.g. SNOWFLAKE_my_connection, and must be a connection in the same workspace; the request is refused with 404 if any is not.

List the agent sessions in the workspace the credential resolves to that the caller can see, most recently updated first. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.

Start a session with an agent and send it a first prompt. The agent replies asynchronously: this returns once the prompt is queued, and the reply is read from GET /sessions/{session_id}/history/messages. incidentId names the incident the session is about. With sessionMode USER, the default, the session is the caller's own, so it needs an OAuth token and an API key gets 400. With INCIDENT it is the incident's, visible across the workspace, and an incident's open session takes the prompt instead of a new one starting. Needs a grant to run the agent, and to view the incident when incidentId is set.

Get an agent session by ID. Returns 404 for a session the caller cannot see, and 403 for one whose agent the caller cannot view. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.

Send a further prompt to an agent session. The agent replies asynchronously: this returns once the prompt is queued, and the reply is read from GET /sessions/{session_id}/history/messages. Needs a grant to run the session's agent. Returns 404 for a session the caller cannot see, and 403 for one whose agent the caller cannot run. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.

Read a page of an agent session's messages, a whole number of complete turns at a time, oldest first. Pass exactly one of before_sequence_id or after_sequence_id. Every message carries a sequenceId of the form <unix-milliseconds>-<counter>, and sequence IDs order as strings. So before_sequence_id set to the current time in milliseconds reads the latest turns, and after_sequence_id=0 reads from the start of the session. Page back with nextBeforeSequenceId while hasPreviousPage is true, and forward with nextAfterSequenceId while hasNextPage is true. A turn still in progress is left out until it completes. Returns 404 for a session the caller cannot see, and 403 for one whose agent the caller cannot view. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.

Ask an agent session to stop working on a prompt, named by the promptAcceptedSequenceId its history records for it. This returns once the cancel is queued, and the history records when the prompt stops. Needs a grant to run the session's agent. Returns 404 for a session the caller cannot see, and 403 for one whose agent the caller cannot run. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.

List the skills available in the workspace the credential resolves to, including those managed by Orchestra. Each skill's markdown is omitted; fetch a single skill to read it.

Create a skill from a markdown document. The markdown must open with YAML frontmatter holding the skill's name and description. Returns 409 if the workspace already has a skill with that name.

Fetch a single skill, including its full markdown.

Delete a skill. Skills managed by Orchestra cannot be deleted. Deleting a skill imported from git removes it from Orchestra only; the file in the repository is left as it is. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.

Replace a skill's markdown. Its name and description are re-read from the new frontmatter. Skills imported from git are read-only: edit the file in the connected repository instead. Skills managed by Orchestra cannot be changed.

Import a skill from a markdown file in the workspace's connected git repository, with the same frontmatter as a created skill. Skills imported from git are read-only: edit the file in the connected repository instead. Returns 422 if no git provider is connected, 404 if the file is not on the branch.

Retrieve the input and output tokens spent by agent sessions in the account, summed across every agent and LLM connection, as totals for the period and in consecutive time buckets. A session counts towards the bucket it was created in.

Requires permission to view account settings.