> For the complete documentation index, see [llms.txt](https://docs.annolab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.annolab.ai/workflows/workflow-executions.md).

# Workflow Executions

Workflow executions track OCR, AI agents, and related tasks running against source files in a project.

A workflow execution is a run of a named workflow (blueprint) against one or more source files. Use this endpoint to check overall status and the status of each task.

## Get Workflow Execution

<mark style="color:blue;">`GET`</mark> `https://api.annolab.ai/v1/workflow/execution/{id}`

Return a workflow execution by id. Requires an API key with "Read" permissions, and the key's user must have view access to the execution's project.

#### Path Parameters

| Name | Type    | Description                                                                                                         |
| ---- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| id   | integer | <p>Id of the workflow execution<br><br><code>url = "<https://api.annolab.ai/v1/workflow/execution/1842>"</code></p> |

#### Headers

| Name          | Type   | Description                                                                                                                                                                  |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Where you put your api key. Getting a workflow execution requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="200 The execution was retrieved" %}

```json
{
    "id": 1842,
    "workflow": "land_title",
    "status": "Running",
    "projectId": 22,
    "startTime": "2026-08-20T18:00:00.000Z",
    "endTime": null,
    "createdBy": {
        "userId": 14,
        "username": "tester"
    },
    "createdAt": "2026-08-20T18:00:00.000Z",
    "sourceIds": [145, 146],
    "tasks": [
        {
            "id": 901,
            "taskType": "OCR",
            "taskName": "OCR",
            "status": "Completed",
            "startTime": "2026-08-20T18:00:01.000Z",
            "endTime": "2026-08-20T18:01:00.000Z"
        },
        {
            "id": 902,
            "taskType": "AI_AGENT",
            "taskName": "Legal Description Extractor",
            "status": "Running",
            "startTime": "2026-08-20T18:01:01.000Z",
            "endTime": null
        }
    ]
}
```

{% endtab %}

{% tab title="403 Forbidden" %}

```json
{
    "message": "You do not have permission to view that workflow."
}
```

{% endtab %}

{% tab title="404 The execution was not found" %}

```json
{
    "message": "No workflow exists with the id <1842>"
}
```

{% endtab %}
{% endtabs %}

Example of how to retrieve a workflow execution

{% tabs %}
{% tab title="Python" %}

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/workflow/execution/1842'

response = requests.get(url, headers=headers)

print(response.json())
```

{% endtab %}
{% endtabs %}

## Execution Object

| Name      | Type                                       | Description                                                                                                                                        |
| --------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id        | Integer                                    | Unique id of the workflow execution                                                                                                                |
| workflow  | String\|null                               | Name of the workflow (blueprint) that was run                                                                                                      |
| status    | String                                     | Overall status inferred from the execution's tasks. See [Execution status](#execution-status).                                                     |
| projectId | Integer                                    | Id of the project that contains this execution                                                                                                     |
| startTime | String\|null                               | ISO formatted DateTime when the execution started                                                                                                  |
| endTime   | String\|null                               | ISO formatted DateTime when the execution finished, or `null` if it is still running                                                               |
| createdBy | Object\|null                               | User who started the execution: `{ "userId": Integer, "username": String }`                                                                        |
| createdAt | String                                     | ISO formatted DateTime when the execution was created                                                                                              |
| sourceIds | Integer\[]                                 | Source file ids processed by this execution. These ids can be used with the [Source Files](/projects-directories-and-sources/source-files.md) API. |
| tasks     | [ExecutionTask](#execution-task-object)\[] | Tasks that make up this execution                                                                                                                  |

### Execution status

`status` is inferred from the task list:

| Status       | Meaning                                                                |
| ------------ | ---------------------------------------------------------------------- |
| Completed    | Every task completed                                                   |
| Running      | At least one task is waiting or running, and none have errored         |
| PartialError | Some tasks errored, and others completed or are still in progress      |
| Error        | At least one task errored and none completed                           |
| Cancelled    | Nothing is in progress or errored, and at least one task was cancelled |

## Execution Task Object

| Name      | Type         | Description                                                                                                                      |
| --------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| id        | Integer      | Unique id of the task                                                                                                            |
| taskType  | String       | Public task type. One of `OCR`, `AI_AGENT`, `AUTOTAGGER`, or `IMPORT_ZIPPED_SOURCE`. Inference tasks are returned as `AI_AGENT`. |
| taskName  | String       | For `AI_AGENT` tasks, the model name. For all other tasks, the task type.                                                        |
| status    | String       | Task status. One of `WaitingUnsubmitted`, `WaitingSubmitted`, `Running`, `Completed`, `Errored`, `Cancelled`, or `Unknown`.      |
| startTime | String\|null | ISO formatted DateTime when the task started, or `null` if it has not started                                                    |
| endTime   | String\|null | ISO formatted DateTime when the task finished, or `null` if it has not finished                                                  |