> ## Documentation Index
> Fetch the complete documentation index at: https://support.myapps.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Workflow API

> Execute a workflow with custom input parameters and receive the full generated result.

### Overview

This endpoint allows you to execute a specific workflow by providing its ID and required input parameters. The response is returned after the model finishes generating — ideal for server-side integrations where you don't need real-time streaming.

### Endpoint

* **HTTP Method**: POST

* **URL**: `/api/v1/run/{workflow_id}`

> Replace `{workflow_id}` with the actual workflow ID (e.g. `wf_abc123`).

### Features

<CardGroup cols={2}>
  <Card title="Full Response" icon="file-lines">
    Receive the **complete generated output** in a single JSON response.
  </Card>

  <Card title="Bearer Key Auth" icon="key">
    Authenticate with your **API secret key** via the Authorization header.
  </Card>

  <Card title="Web Search Citations" icon="globe">
    Automatically receive **source citations** when the model uses web search.
  </Card>

  <Card title="Rate Limit Headers" icon="gauge">
    Monitor your usage with **rate limit headers** in every response.
  </Card>
</CardGroup>

### Authentication

Requires a Bearer token in the `Authorization` header.

```
Authorization: Bearer YOUR_API_KEY
```

### Request

**Path Parameters**

| Name         | Required | Type   | Description                                      |
| ------------ | -------- | ------ | ------------------------------------------------ |
| workflow\_id | Yes      | string | The ID of the workflow to run (e.g. `wf_abc123`) |

**Request Body**

Content-Type: `application/json`

Pass your workflow's input variables as key/value pairs. The keys must match the variable names defined in your workflow template.

```json theme={null}
{
  "story": "a story about a dog named charlie"
}
```

### Example Request

```bash theme={null}
curl --request POST \
     --url https://aitutor-api.vercel.app/api/v1/run/wf_abc123 \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{"story": "a story about a dog named charlie"}'
```

### Response

A successful response returns the full generated text and optional citations:

```json theme={null}
{
  "success": true,
  "result": "Once upon a time, there was a friendly dog named Charlie...",
  "citations": ["https://example.com/source"]
}
```

| Field     | Type      | Description                                        |
| --------- | --------- | -------------------------------------------------- |
| success   | boolean   | Always `true` on success                           |
| result    | string    | The generated text output                          |
| citations | string\[] | Optional. Web sources if the model used web search |

**Response Headers**

| Header                | Description                  |
| --------------------- | ---------------------------- |
| x-ratelimit-limit     | Your rate limit per window   |
| x-ratelimit-remaining | Remaining requests in window |

### Error Responses

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock">
    Missing or invalid API key.

    ```json theme={null}
    {
      "error": "Unauthorized. Please provide a valid secret key.",
      "success": false
    }
    ```
  </Accordion>

  <Accordion title="402 Payment Required" icon="credit-card">
    No credits remaining on the account.

    ```json theme={null}
    {
      "error": "No credits remaining. Please add credits to continue using the service.",
      "success": false,
      "code": "invalid_billing"
    }
    ```
  </Accordion>

  <Accordion title="404 Not Found" icon="circle-question">
    Workflow not found or not published.

    ```json theme={null}
    {
      "error": "Workflow not found",
      "success": false,
      "code": "workflow_not_found"
    }
    ```
  </Accordion>

  <Accordion title="429 Too Many Requests" icon="shield-check">
    Rate limit exceeded.

    ```json theme={null}
    {
      "error": "Rate limit exceeded",
      "success": false
    }
    ```
  </Accordion>

  <Accordion title="500 Internal Server Error" icon="triangle-exclamation">
    Something went wrong during execution.

    ```json theme={null}
    {
      "error": "Failed to run workflow",
      "success": false,
      "code": "internal_server_error"
    }
    ```
  </Accordion>
</AccordionGroup>

### Code Examples

<AccordionGroup>
  <Accordion title="Python" icon="python">
    ```python theme={null}
    import requests

    url = "https://aitutor-api.vercel.app/api/v1/run/wf_abc123"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    }
    data = {
        "story": "a story about a dog named charlie",
    }

    response = requests.post(url, headers=headers, json=data)
    print(response.json())
    ```
  </Accordion>

  <Accordion title="Node.js" icon="node-js">
    ```javascript theme={null}
    const response = await fetch(
      "https://aitutor-api.vercel.app/api/v1/run/wf_abc123",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          story: "a story about a dog named charlie",
        }),
      }
    );

    const data = await response.json();
    console.log(data.result);
    ```
  </Accordion>

  <Accordion title="cURL" icon="terminal">
    ```bash theme={null}
    curl --request POST \
         --url https://aitutor-api.vercel.app/api/v1/run/wf_abc123 \
         --header 'Authorization: Bearer YOUR_API_KEY' \
         --header 'Content-Type: application/json' \
         --data '{"story": "a story about a dog named charlie"}'
    ```
  </Accordion>
</AccordionGroup>

### Additional Notes

* **Input Variables**: The request body keys must exactly match the variable names in your workflow template (e.g. `{{story}}`).

* **Max Duration**: Requests can run for up to 300 seconds before timing out.

* **Credits**: Each successful run deducts credits from your organization's balance based on token usage.

* **Streaming Alternative**: If you need real-time output as it's generated, use the [Streaming Workflow](/docs/stream-workflow) endpoint instead.