> ## Documentation Index
> Fetch the complete documentation index at: https://velt-mintlify-e6426361.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List approval executions (v2)

> List approval workflow executions filtered by definition, status, or time range using the Velt v2 REST API to monitor runs and reporting dashboards.

Use this API to paginate through workflow executions. Filter by `definitionId` and/or `status`.

# Endpoint

`POST https://api.velt.dev/v2/workflow/executions/list`

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="definitionId" type="string">
      Filter by definition.
    </ParamField>

    <ParamField body="status" type="string">
      Filter by status. One of: `pending` / `running` / `completed` / `failed` / `cancelled`.
    </ParamField>

    <ParamField body="pageSize" type="integer">
      1–500.
    </ParamField>

    <ParamField body="cursor" type="string">
      Pass back the previous response's `nextCursor`.
    </ParamField>

    <Note>
      `List Executions` does not accept `organizationId` or `documentId` filters in v1. To narrow the result by scope, filter on the returned `ExecutionView.steps[].metadata` client-side, or paginate with a tighter `definitionId` filter.
    </Note>
  </Expandable>
</ParamField>

## **Example Requests**

#### List running executions for a definition

```JSON theme={null}
{
  "data": {
    "definitionId": "marketing-copy-approval",
    "status": "running",
    "pageSize": 50
  }
}
```

#### Paginate

```JSON theme={null}
{
  "data": {
    "pageSize": 50,
    "cursor": "eyJvZmZzZXQiOjEwMH0="
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "items": [ /* ExecutionView[] */ ],
    "nextCursor": "eyJvZmZzZXQiOjEwMH0=",
    "hasMore": true
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "items": [],
      "nextCursor": "eyJvZmZzZXQiOjEwMH0=",
      "hasMore": true
    }
  }
  ```
</ResponseExample>