---
title: "Create a run within a pipeline."
method: POST
path: "/orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs"
tags: ["public", "PipelineRuns"]
---

# Create a run within a pipeline.

`POST /orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs`

## Request

- Base URL: `https://api.humanitec.io`
- URL: `https://api.humanitec.io/orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs`
- Auth: none declared

## Path parameters

- `orgId` string, required
- `appId` string, required
- `pipelineId` string, required

## Query parameters

- `dry_run` boolean

## Headers

- `Idempotency-Key` string

## Request body

- PipelineRunCreateBody: The parameters for creating a new Run for the Pipeline.
  - `inputs` object, required: The inputs provided for this Run.

## Response `201`

Successful creation response.

- PipelineRun: Details of a Run within the Pipeline.
  - `id` string, required: The unique id of the Run.
  - `etag` string, required: The current entity tag value for this Run.
  - `org_id` string, required: The id of the Organization containing this Run.
  - `app_id` string, required: The id of the Application containing this Run.
  - `env_ids` string[], required: Environments linked to this Pipeline Run through input parameters or step executions.
  - `pipeline_id` string, required: The id of the Pipeline associated with the Run.
  - `pipeline_version` string, required: The id of the Pipeline Version associated with the Run.
  - `status` string, required: The current status of this Run.
  - `status_message` string, required: A human-readable message indicating the reason for the status.
  - `created_at` string, date-time, required: The date and time when this Run was first created.
  - `created_by` string, required: User id that created or triggered the Run.
  - `executing_at` string, date-time: The date and time when this Run entered executing status.
  - `cancellation_requested_at` string, date-time: The date and time when cancellation of this Run was requested.
  - `completed_at` string, date-time: The date and time when this Run entered a successful, failed, or cancelled status.
  - `timeout_seconds` integer, required: The timeout for this Run.
  - `trigger` string, required: The trigger type that was triggered this Run to start.
  - `inputs` object, required: The inputs that were provided for this Run.
  - `run_as` string, required: The user id that the pipeline run is executing as when it calls Humanitec APIs.
  - `concurrency_group` string: The optional concurrency group for this run within the application
  - `waiting_for` object, required: Aggregated events on which run's jobs are waiting for

## Other responses

- `204`: The request was valid, but no Pipeline Run was created.
- `400`: The request was invalid. More detail can be found in the error body.
- `404`: Either the resource or a related resource could not be found. More detail can be found in the error body.
- `409`: The request itself is valid however it could not be applied based on the current state of the resource. More detail can be found in the error body.
- `422`: Server understands the content type of the request, and the syntax of the request is correct, but it was unable to process the contained instructions

## Changes

- **2025-06-21** `4db6186594e3`: 1 warning
  - for the `path` request parameter `appId`, the maxLength was set to `50`

[Operation history](https://skmtc.dev/humanitec/apis/humanitec-api/changes/orgs/:orgId/apps/:appId/pipelines/:pipelineId/runs/post.md)

---

[API](https://skmtc.dev/humanitec/apis/humanitec-api.md) - [All operations](https://skmtc.dev/humanitec/apis/humanitec-api/llms.txt) - [OpenAPI document](https://skmtc.dev/humanitec/apis/humanitec-api/revisions/74d8727ef6b1?raw)