> ## 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.

# Poll iBlueprint execution status, steps, and progress

> Poll the status of an iBlueprint execution by ID to track progress, current step, completed and failed step counts, and whether the run is awaiting user input.

The `execution.getExecutionStatus` procedure reads the current state of a blueprint execution from the database. Poll this endpoint after triggering an async execution with `execution.executeBlueprintWithLogging` to track progress and detect completion or failure. The `progress` field (0–100) and `completedSteps` count update as nodes finish, giving you a live view into long-running workflows.

## Request

**Procedure type:** query (HTTP `GET`)

**Endpoint:**

```
GET https://api.iblueprint.ai/api/trpc/execution.getExecutionStatus
```

### Parameters

<ParamField query="input" type="object" required>
  A URL-encoded JSON object with a `json` key containing the parameter below.
</ParamField>

<ParamField query="json.executionId" type="string" required>
  The execution ID returned by `blueprint.execute` or `execution.executeBlueprintWithLogging`.
</ParamField>

## Response

<ResponseField name="id" type="string">The execution ID.</ResponseField>

<ResponseField name="status" type="string">
  Current execution status. One of:

  * `running` — actively processing nodes
  * `completed` — all nodes finished successfully
  * `failed` — one or more nodes failed and execution stopped
  * `paused` — execution is paused (e.g. awaiting human-in-the-loop input)
  * `not_found` — no execution record exists for this ID
</ResponseField>

<ResponseField name="progress" type="number">Integer percentage (0–100) of nodes completed.</ResponseField>
<ResponseField name="startTime" type="string">ISO 8601 timestamp when execution began.</ResponseField>
<ResponseField name="endTime" type="string">ISO 8601 timestamp when execution finished. `null` if still running.</ResponseField>
<ResponseField name="totalSteps" type="number">Total number of nodes in this blueprint run.</ResponseField>
<ResponseField name="completedSteps" type="number">Number of nodes that have finished successfully.</ResponseField>
<ResponseField name="failedSteps" type="number">Number of nodes that failed.</ResponseField>
<ResponseField name="steps" type="array">Array of step-level execution records, each describing an individual node run.</ResponseField>
<ResponseField name="logs" type="array">Array of log entries produced during execution.</ResponseField>
<ResponseField name="currentStep" type="string">ID of the node currently executing. `undefined` if no node is actively running.</ResponseField>
<ResponseField name="awaitingInput" type="object">Present when `status` is `paused` and the blueprint is waiting for user input. Contains details about what input is required.</ResponseField>

## Polling pattern

Poll the status endpoint at a regular interval until `status` is `completed` or `failed`. A 2–5 second interval is appropriate for most blueprints.

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://api.iblueprint.ai/api/trpc/execution.getExecutionStatus" \
    --data-urlencode 'input={"json":{"executionId":"exec_1733050800000_a3b7z"}}' \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  async function pollExecution(executionId, apiKey, intervalMs = 3000) {
    while (true) {
      const params = new URLSearchParams({
        input: JSON.stringify({ json: { executionId } }),
      });

      const response = await fetch(
        `https://api.iblueprint.ai/api/trpc/execution.getExecutionStatus?${params}`,
        { headers: { Authorization: `Bearer ${apiKey}` } }
      );

      const { result } = await response.json();
      const status = result.data.json;

      console.log(`Progress: ${status.progress}% (${status.completedSteps}/${status.totalSteps} steps)`);

      if (status.status === 'completed') {
        console.log('Execution completed.');
        return status;
      }

      if (status.status === 'failed') {
        throw new Error(`Execution failed after ${status.failedSteps} failed steps.`);
      }

      await new Promise((resolve) => setTimeout(resolve, intervalMs));
    }
  }

  const finalStatus = await pollExecution('exec_1733050800000_a3b7z', 'YOUR_API_KEY');
  ```
</CodeGroup>

### Sample response (in progress)

```json theme={null}
{
  "result": {
    "data": {
      "json": {
        "id": "exec_1733050800000_a3b7z",
        "status": "running",
        "progress": 50,
        "startTime": "2024-12-01T10:00:00Z",
        "endTime": null,
        "totalSteps": 4,
        "completedSteps": 2,
        "failedSteps": 0,
        "steps": [...],
        "logs": [...],
        "currentStep": "node-3",
        "awaitingInput": null
      }
    }
  }
}
```

### Sample response (completed)

```json theme={null}
{
  "result": {
    "data": {
      "json": {
        "id": "exec_1733050800000_a3b7z",
        "status": "completed",
        "progress": 100,
        "startTime": "2024-12-01T10:00:00Z",
        "endTime": "2024-12-01T10:00:12Z",
        "totalSteps": 4,
        "completedSteps": 4,
        "failedSteps": 0,
        "steps": [...],
        "logs": [...],
        "currentStep": null,
        "awaitingInput": null
      }
    }
  }
}
```