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

# Get Execution Events

Use this API to retrieve a cursor-paginated view of the external-facing event stream for an execution. Use this to reconcile after a webhook outage.

# Endpoint

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

# 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="executionId" type="string" required>
      The execution to read events from.
    </ParamField>

    <ParamField body="sinceSeq" type="integer">
      Default 0. Returns events with `seq > sinceSeq`.
    </ParamField>

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

<Note>
  Only externally-visible event types are returned: `execution.dispatched`, `execution.completed`, `execution.failed`, `execution.cancelled`, `step.awaiting-approval`, `step.completed`, `step.failed`, `step.breached`, `step.cancelled`, `group.quorum-met`, `loop.iteration-started`, `loop.exhausted`. Internal-only events (`step.scheduled`, `step.started`, `step.retried`, `step.resumed`, `step.response-recorded`, `step.overridden`, `parallel-group.completed`, `idempotency.suppressed`) fill `seq` gaps but are filtered out — your stream may have non-contiguous `seq` values.
</Note>

For the full external event catalog, see [Event reference](/ai/approval-engine/customize-behavior#event-reference).

## **Example Requests**

#### Reconcile after a webhook outage

```JSON theme={null}
{
  "data": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "sinceSeq": 5
  }
}
```

#### Paginate through all events

```JSON theme={null}
{
  "data": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "sinceSeq": 0,
    "pageSize": 100
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "events": [
      {
        "eventId": "evt_abc...",
        "seq": 7,
        "type": "step.awaiting-approval",
        "stepId": "step_agent-draft_..._lwofay__to__human-legal",
        "timestamp": 1777374842347,
        "correlationId": "corr_campaign_42",
        "data": {
          "waitingForReviewers": 1,
          "mandatoryCount": 1,
          "resumeKey": "human:..."
        }
      }
    ],
    "nextCursor": 12,
    "hasMore": false
  }
}
```

#### Failure Response

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

**Errors:** `NOT_FOUND` / `INVALID_ARGUMENT`.

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "executionId": "exec_1777374504255_xzy43k9q",
      "events": [],
      "nextCursor": 12,
      "hasMore": false
    }
  }
  ```
</ResponseExample>