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

# Check Status

> Poll the status of an interactive notification request and see individual user responses.

## Endpoint

```
GET /api/notify/status/{request_id}
```

## Path parameters

<ParamField path="request_id" type="string" required>
  The `request_id` returned when sending an [interactive notification](/api-reference/interactive-notifications). Fire-and-forget notifications do not return a `request_id`.
</ParamField>

## Headers

| Header      | Required | Description                                         |
| ----------- | -------- | --------------------------------------------------- |
| `X-API-Key` | Yes      | Your API key (must belong to the same organization) |

## Response

<ResponseField name="status" type="string">
  Overall request status:

  * `"pending"` — Waiting for responses or timeout
  * `"finished"` — All users responded or timeout reached
</ResponseField>

<ResponseField name="external_reference_id" type="string">
  Your correlation ID, if provided in the original request.
</ResponseField>

<ResponseField name="responses" type="array">
  One entry per recipient:

  | Field          | Type           | Description                                                      |
  | -------------- | -------------- | ---------------------------------------------------------------- |
  | `user_email`   | string         | Recipient email                                                  |
  | `option_value` | string \| null | The `value` of the chosen option, or `null` if not yet responded |
  | `timestamp`    | string \| null | ISO 8601 timestamp of the response                               |
  | `expired`      | boolean        | Whether this user's response window expired                      |
</ResponseField>

## Example

```bash theme={null}
curl https://app.nextks.com/api/notify/status/req_a1b2c3d4e5f6 \
  -H "X-API-Key: YOUR_API_KEY"
```

### Pending response

```json theme={null}
{
  "status": "pending",
  "external_reference_id": "deploy-v2.4.1",
  "responses": [
    {
      "user_email": "alice@company.com",
      "option_value": "approve",
      "timestamp": "2026-02-11T14:23:01.000Z",
      "expired": false
    },
    {
      "user_email": "bob@company.com",
      "option_value": null,
      "timestamp": null,
      "expired": false
    }
  ]
}
```

### Finished response

```json theme={null}
{
  "status": "finished",
  "external_reference_id": "deploy-v2.4.1",
  "responses": [
    {
      "user_email": "alice@company.com",
      "option_value": "approve",
      "timestamp": "2026-02-11T14:23:01.000Z",
      "expired": false
    },
    {
      "user_email": "bob@company.com",
      "option_value": null,
      "timestamp": null,
      "expired": true
    }
  ]
}
```

## Errors

| Status | Details                                                  |
| ------ | -------------------------------------------------------- |
| `400`  | Invalid `request_id` format                              |
| `401`  | Invalid API key                                          |
| `404`  | Request not found or belongs to a different organization |