---
title: "Selecting a workflow to run using pipeline parameters"
description: "\"A how-to guide for selecting a workflow to run using pipeline parameters.\""
doc_version: "unversioned"
last_updated: "2026-07-24"
---

> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Selecting a workflow to run using pipeline parameters

You might find that you want to manually trigger a specific workflow to run using the API but still run a workflow on every push to your project. To achieve this, use [Pipeline Parameters](https://circleci.com/docs/guides/orchestrate/pipeline-variables/#pipeline-parameters-in-configuration) to decide which workflow(s) to run.

## config.yml

The following example defaults to running the `build` workflow, but allows control of which other workflow to run using the API:

```yaml
version: 2.1

parameters:
  action:
    type: enum
    enum: [build, report]
    default: build

jobs:
  build:
    docker:
      - image: cimg/base:2023.11
    steps:
      - checkout
      - run: ./run-tests.sh

  report:
    docker:
      - image: cimg/base:2023.11
    steps:
      - checkout
      - run: ./create-report.sh

workflows:
  build:
    when: pipeline.parameters.action == "build" # only run the build workflow if the action parameter is set to "build"
    jobs:
      - build

  report:
    when: pipeline.parameters.action == "report" # only run the report workflow if the action parameter is set to "report"
    jobs:
      - report
```

## Supply parameter with API

The `action` parameter will default to `build` on pushes to the project. Below is an example of supplying a different value to `action` using the API v2 [Trigger a New Pipeline](https://circleci.com/docs/api/v2/#operation/triggerPipeline) endpoint to select a different workflow to run.

In this example, the workflow named `report` would run. Remember to substitute [`project-slug`](https://circleci.com/docs/guides/toolkit/api-developers-guide/#getting-started-with-the-api) with your values.

For GitHub App, GitLab or Bitbucket Data Center pipelines, use the [Trigger a new pipeline endpoint](https://circleci.com/docs/api/v2/index.html#tag/Pipeline/operation/triggerPipelineRun) rather than the endpoint used in this example.

```shell
curl -X POST https://circleci.com/api/v2/project/{project-slug}/pipeline \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Circle-Token: API_KEY" \
  -d '{ "parameters": { "action": report } }'
```

**To find your project slug, follow these steps:**

1.  Head to the [CircleCI web app](https://app.circleci.com/home) and select your org from the cards on your user homepage.
    
2.  Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
    
3.  Select the ellipsis menu next to your project and select **Project Settings**. The project slug is listed on the project settings homepage.
    
    *   **GitHub App**: Project slug starts with `circleci` followed by UUIDs. For example, `circleci/34R3kN5RtfEE7v4sa4nWAU/4nYdoKGkb6RXn7JGt8SQtg`.
        
    *   **GitHub OAuth app**: Project slug is human readable. For example, `github/circleci/circleci-demo-workflows`.
        
    

## Next steps

For more information on using API v2 endpoints, see the [API Reference Documentation](https://circleci.com/docs/api/v2/) and the [API Developers Guide](https://circleci.com/docs/guides/toolkit/api-developers-guide/#example-end-to-end-api-request) end-to-end example.