---
title: "Trigger pipeline"
method: POST
path: "/v2/pipelines/{pipeline_key}/trigger"
tags: ["Pipelines"]
---

# Trigger pipeline

`POST /v2/pipelines/{pipeline_key}/trigger`

Triggers a pipeline run manually, outside of the normal schedule. The pipeline fetches new data from the source and processes it through the agent. Returns the created run.

## Path parameters

- `pipeline_key` string, required — The unique key for the pipeline. You can provide the key, or the platform generates one.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `201`

The created pipeline run.

- PipelineRun — A single execution of a pipeline. Each run fetches data from the source and creates one agent session per record it processes. A record whose agent `run_condition` evaluated to false gets no session, and a record already processed at the same watermark reuses its prior session.
  - `id` string, required — The unique identifier for a pipeline run.
  - `pipeline_key` string, required — The unique key for the pipeline. You can provide the key, or the platform generates one.
  - `agent_key` string, required — A unique key that identifies an agent.
  - `status` 'running' | 'completed' | 'failed' | 'cancelled', required — The status of a pipeline run.
  - `trigger_type` 'scheduled' | 'manual' | 'retry', required — What initiated the pipeline run.
  - `records_fetched` integer, required — Number of records this run took from the source for processing, counting both upserts and deletions. Records the run drops before processing, for example source-reported deletions during a full refresh, are excluded. A retry run counts the dead letters it fetches.
  - `records_processed` integer, required — Number of records successfully processed by the agent. Excludes records counted by `records_skipped`.
  - `records_skipped` integer, required — Number of records the run neither processed nor failed. Either the agent's `run_condition` evaluated to false, so no session was created, or the judge agent's `run_condition` evaluated to false, so nothing verified the record. Disjoint from `records_processed` and `records_failed`.
  - `records_failed` integer, required — Number of records that failed processing.
  - `error` string, nullable — Error details if the run failed.
  - `started_at` string, date-time, nullable — When the run started executing.
  - `completed_at` string, date-time, nullable — When the run finished.
  - `created_at` string, date-time, required — When the run was created.

## Other responses

- `403` — Permissions do not allow triggering this pipeline.
- `404` — Pipeline not found.
- `409` — A run is already in progress for this pipeline.

## Changes

- **2026-08-16** `83554494d7f8` — 1 info
  - added the required property `records_skipped` to the response with the `201` status

[Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/pipelines/:pipeline_key/trigger/post.md)

---

[API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/revisions/de6b34bc4a4f?raw)