> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/apis-and-mcp/running-workflows-and-selecting-versions.md).

# Running Workflows and Selecting Versions

The v2 run API starts a workflow asynchronously and returns a run identifier. Follow that run to completion before using its result.

![Start one run, then follow its ID](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FvrcwFuiNx75Wv9Ad68ro%2Frunning-workflows-and-selecting-versions.png?alt=media)

Use your actual input schema and a saved version number. Creation is asynchronous: inspect the same run until it succeeds, fails, is cancelled, or needs a human response.

<details>

<summary>Copy the example</summary>

```http
POST /v2/runs
Content-Type: application/json

{
  "project_id": "<project-id>",
  "project_version": 3,
  "input": {"<input-node-id>": "<input-value>"}
}

# Use the run ID returned by the create response.
GET /v2/runs/{run_id}
```

</details>

## Before you begin

A public API credential with project execution access and valid project inputs.

## Key concepts

| Term                   | Definition                                                                                                                                          |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Run                    | One execution of a project. Use its run ID to retrieve that execution’s state, input, output, and errors.                                           |
| Asynchronous operation | An operation acknowledged before its processing is complete. Retain its handle and follow its documented status or completion mechanism.            |
| Terminal state         | A state indicating that a run has ended, such as succeeded, failed, or cancelled. Stop normal completion polling only after a final state is known. |
| Paused                 | A run state that waits for a supported response before it can continue. Respond to the existing run instead of starting a new one.                  |

## Configuration options

| Option          | Purpose                                      | Behavior                                                 |
| --------------- | -------------------------------------------- | -------------------------------------------------------- |
| Project version | A specific saved configuration of a project. | Select it explicitly when a result must be reproducible. |

## Start a workflow run

1. Create the run using the project ID, input object, and intended project\_version.
2. Save the returned run ID and poll its status through the public run endpoint.
3. Handle paused, failed, or cancelled states separately from succeeded.

The client retrieves the result of the same execution it started.

## Behavior and limitations

On v2 runs, omitted or null project\_version selects published content, -1 selects editable content, and a nonnegative integer selects a saved version. Creation returning 201 does not mean execution succeeded. Do not reuse these selector rules for legacy inference.

| Stage                  | Public operation        |
| ---------------------- | ----------------------- |
| Start                  | `POST /v2/runs`         |
| Read status and result | `GET /v2/runs/{run_id}` |

Keep the `input` shape consistent with the project’s documented input schema.

### Request body

Replace the placeholders with your project ID and its actual input field key. This request uses the current published version because it omits `project_version`.

```json
{
  "project_id": "<project-id>",
  "input": {
    "<input-node-id>": "<input-value>"
  }
}
```

Read `GET /v2/projects/{project_id}/io-schema` to identify the project’s input contract. Supply an object or list instead of text when the selected field requires it. Keep the schema’s selected version consistent with the version you run.

## Related resources

[API Versions and Compatibility](https://docs.stackai.com/technical-reference/apis-and-mcp/api-versions-and-compatibility.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/apis-and-mcp/running-workflows-and-selecting-versions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
