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

# Execute an iBlueprint blueprint and get results

> Trigger a synchronous iBlueprint blueprint run by ID, pass runtime variables, and receive an execution ID and result — or use async logging for long-running workflows.

The `blueprint.execute` procedure runs a blueprint synchronously via the iBlueprint runner service and returns the result once execution completes. This is the fastest path for short-lived blueprints where you need the output inline. For long-running blueprints, use `execution.executeBlueprintWithLogging` instead, which logs progress to the database so you can poll for status with `execution.getExecutionStatus`.

## Request

**Procedure type:** mutation (HTTP `POST`)

**Endpoint:**

```
POST https://api.iblueprint.ai/api/trpc/blueprint.execute
Content-Type: application/json
```

**Body shape:**

```json theme={null}
{ "json": { ...parameters... } }
```

### Parameters

<ParamField body="json.id" type="string" required>
  UUID of the blueprint to execute. You must have access to the blueprint (owner, collaborator, org member, or the blueprint is public).
</ParamField>

<ParamField body="json.variables" type="object">
  Key-value map of runtime variables to inject into the blueprint. Nodes reference variables using `{{variable_name}}` syntax in their configuration. Defaults to an empty object if omitted.

  ```json theme={null}
  { "email_body": "Hi team, see attached report..." }
  ```
</ParamField>

## Response

<ResponseField name="success" type="boolean">`true` if the runner accepted and completed the execution.</ResponseField>
<ResponseField name="executionId" type="string">Unique ID for this execution run, in the format `exec_{timestamp}_{random}`.</ResponseField>
<ResponseField name="result" type="object">The raw output returned by the runner service. Shape varies by blueprint node configuration.</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.iblueprint.ai/api/trpc/blueprint.execute" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "json": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "variables": {
          "email_body": "Hi team, please review the attached quarterly report.",
          "tone": "formal"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.iblueprint.ai/api/trpc/blueprint.execute',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        json: {
          id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
          variables: {
            email_body: 'Hi team, please review the attached quarterly report.',
            tone: 'formal',
          },
        },
      }),
    }
  );

  const { result } = await response.json();
  const { success, executionId, result: runResult } = result.data.json;
  console.log('Execution ID:', executionId);
  console.log('Output:', runResult);
  ```
</CodeGroup>

### Sample response

```json theme={null}
{
  "result": {
    "data": {
      "json": {
        "success": true,
        "executionId": "exec_1733050800000_a3b7z",
        "result": {
          "summary": "The team is requested to review the quarterly report attached to the email.",
          "steps": [...]
        }
      }
    }
  }
}
```

## Asynchronous execution with logging

For blueprints that may take more than a few seconds, use `execution.executeBlueprintWithLogging`. This procedure writes step-level progress to the database as execution proceeds. You can then poll `execution.getExecutionStatus` with the returned `executionId` until `status` is `completed` or `failed`.

```bash theme={null}
# Start async execution
curl -X POST "https://api.iblueprint.ai/api/trpc/execution.executeBlueprintWithLogging" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "nodes": [...],
      "options": { "blueprintId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
    }
  }'

# Then poll status
curl -G "https://api.iblueprint.ai/api/trpc/execution.getExecutionStatus" \
  --data-urlencode 'input={"json":{"executionId":"exec_1733050800000_a3b7z"}}' \
  -H "Authorization: Bearer YOUR_API_KEY"
```

See [Execution Status](/api-reference/executions/status) for the full polling guide.

## Error handling

If the blueprint has no nodes, or if the runner service is unavailable, the API returns an error:

```json theme={null}
{
  "error": {
    "json": {
      "message": "Blueprint has no nodes to execute",
      "code": -32600,
      "data": { "code": "BAD_REQUEST", "httpStatus": 400 }
    }
  }
}
```