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

# GET /v1/subscriptions

> List all subscriptions for your API key. Returns a paginated list ordered by creation date descending. Address filters are not inlined in list responses.

Use this endpoint to retrieve all subscriptions associated with your API key. Results are ordered by creation date, newest first. To keep response sizes predictable, list responses do not include address filters or the signing secret — use `GET /v1/subscriptions/:id` to fetch a specific subscription with its inlined addresses.

## Request

**`GET /v1/subscriptions`**

### Headers

| Header          | Required | Description               |
| --------------- | -------- | ------------------------- |
| `Authorization` | Yes      | `Bearer oth_YOUR_API_KEY` |

### Query parameters

<ParamField query="limit" type="integer" default="50">
  Number of subscriptions to return per page. Accepted range: 1–200. Values above 200 are clamped to 200.
</ParamField>

<ParamField query="nextPageToken" type="string">
  Opaque cursor returned in a previous response. Pass this value to retrieve the next page of results. Omit this parameter to start from the beginning of the list.
</ParamField>

### Example request

```bash theme={null}
curl "https://api.offthehook.dev/v1/subscriptions?limit=20" \
  -H "Authorization: Bearer oth_YOUR_API_KEY"
```

## Response

**`200 OK`**

```json theme={null}
{
  "items": [
    {
      "id": "sub_2QkP9aB7xN...",
      "destination": { "type": "https", "url": "https://your-server.example.com/webhooks" },
      "events": ["wallet.transfer.broadcasted"],
      "filters": { "addresses": [] },
      "status": "enabled",
      "description": "Production wallet monitor",
      "dateCreated": "2026-05-08T12:00:00Z",
      "dateUpdated": "2026-05-08T12:00:00Z"
    }
  ],
  "nextPageToken": "v1:..."
}
```

<Info>
  List responses do not include `destination.secret` or inline address filters. To retrieve a subscription's address filters, call `GET /v1/subscriptions/:id`.
</Info>

### Response fields

<ResponseField name="items" type="object[]" required>
  Array of subscription objects for the current page. Empty array when no subscriptions exist.

  <Expandable title="item properties">
    <ResponseField name="items[].id" type="string" required>
      Unique subscription identifier, prefixed with `sub_`.
    </ResponseField>

    <ResponseField name="items[].destination" type="object" required>
      Delivery target. Includes `type` and `url`. The `secret` field is never present in list responses.
    </ResponseField>

    <ResponseField name="items[].events" type="string[]" required>
      Event kinds this subscription is subscribed to.
    </ResponseField>

    <ResponseField name="items[].filters" type="object" required>
      Contains an empty `addresses` array. Address filters are not inlined in list responses — use `GET /v1/subscriptions/:id` to retrieve them.
    </ResponseField>

    <ResponseField name="items[].status" type="string" required>
      `"enabled"` or `"disabled"`.
    </ResponseField>

    <ResponseField name="items[].description" type="string" required>
      Human-readable label. Empty string if none was set.
    </ResponseField>

    <ResponseField name="items[].dateCreated" type="string" required>
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="items[].dateUpdated" type="string" required>
      ISO 8601 timestamp of the most recent update.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextPageToken" type="string">
  Opaque cursor for the next page. Pass this as the `nextPageToken` query parameter in your next request. When this field is absent, you have reached the last page.
</ResponseField>

### Pagination

Pass `nextPageToken` from each response as a query parameter to retrieve the following page. When the field is absent from the response, you have retrieved all subscriptions. Pagination tokens are versioned and opaque — do not parse or construct them manually.

```bash theme={null}
# First page
curl "https://api.offthehook.dev/v1/subscriptions?limit=20" \
  -H "Authorization: Bearer oth_YOUR_API_KEY"

# Next page using the token from the previous response
curl "https://api.offthehook.dev/v1/subscriptions?limit=20&nextPageToken=v1:..." \
  -H "Authorization: Bearer oth_YOUR_API_KEY"
```

## Errors

| Code                       | Description                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| `invalid_pagination_token` | The `nextPageToken` value is malformed or was issued by an incompatible version of the API. |
| `unauthorized`             | The `Authorization` header is missing or the API key is invalid.                            |