# List notifications

List the project's notification history, including notifications waiting for their subscription
condition, with filtering and pagination. Filters combine with AND, and filtering by a channel
or subscription that has since been deleted still works, because the history keeps the identity
it was created with.

Endpoint: GET /notifications
Version: 2.0.0
Security: Auth

## Security:

  - `Auth` (unknown)
    apiKey in header X-Api-Key scopes: api:channel:read

## Query parameters:

  - `limit` (integer)
    Maximum number of items to return.

  - `page` (integer)
    Page number for pagination.

  - `channel_id` (string)
    Filter by the channel the notification was sent to. The channel need not still exist.

  - `subscription_id` (string)
    Filter by the subscription that selected the transaction. The subscription need not still exist.

  - `status` (string)
    Filter by current notification status.

  - `chain_gid` (string)
    Filter by the network of the transaction. Tests carry no network and are excluded.

  - `txid` (string)
    Filter by transaction. Requires chain_gid, since a transaction id alone is ambiguous across networks.

  - `is_test` (boolean)
    Filter by whether the notification is a channel test. Omit it to get both tests and transaction notifications.

  - `date_from` (string)
    Filter notifications created from this moment on (inclusive, RFC 3339).

  - `date_to` (string)
    Filter notifications created before this moment (exclusive, RFC 3339). It has to follow date_from.

  - `sort_by` (string)
    Field to sort results by. Use `-` prefix for descending order.

## Response 200:

  - `200` (unknown)
    List of notifications with pagination.

## Response 200 fields (application/json):

  - `items` (array, required)

  - `items.id` (string, required)
    Unique identifier (UUID).
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `items.subscription_id` (any, required)
    Subscription that selected the transaction, or null for a channel test.

  - `items.is_test` (boolean, required)
    Whether this is a channel diagnostic rather than a real transaction notification.

  - `items.chain_gid` (string)
    Blockchain identifier in [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) format.
Format: `{namespace}:{reference}`
- **namespace**: Ecosystem identifier (3-8 chars, lowercase)
- **reference**: Blockchain identifier within namespace (1-32 chars)

**Examples**:
- `eip155:1`: Ethereum mainnet
- `eip155:56`: BNB Smart Chain mainnet
- `eip155:137`: Polygon mainnet
- `bip122:000000000019d6689c085ae165831e93`: Bitcoin mainnet
- `tron:728126428`: Tron mainnet
    Example: eip155:1

  - `items.txid` (string)
    Native transaction id of the chain (hash for EVM and Tron, txid for Bitcoin).
    Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

  - `items.status` (string, required)
    State of one notification. It describes delivery bookkeeping, not blockchain confirmation and
not the state of the channel. A canceled or failed notification may still have been seen by the
receiver, so there is no single success flag.
    Enum: "waiting", "scheduled", "sending", "delivered", "failed", "canceled", "unknown"

  - `items.reason` (any, required)
    Why the notification reached its status, or null while there is nothing to explain.

  - `items.attempt_count` (integer, required)
    Count of authorized attempts. Authorization is not proof of remote receipt.
    Example: 2

  - `items.automatic_attempt_count` (integer, required)
    Authorized automatic attempts, which is attempt_count minus manual_attempt_count.

  - `items.resend_status` (any, required)
    Progress of a manual resend, or null when none is running.

  - `items.last_attempt_at` (any, required)
    When the most recent attempt was authorized, or null before any attempt.

  - `items.last_attempt_status` (any, required)
    Status of that same most recent attempt, or null before any attempt.

  - `items.next_attempt_at` (any, required)
    When the next automatic attempt is due, or null without automatic eligibility.

  - `items.payload_version` (any, required)
    Webhook body version actually frozen, or null before preparation and for Telegram. It is
never substituted from the channel's live configuration.

  - `items.event_name` (any, required)
    Logical event name frozen with the content, or null before preparation.

  - `meta` (object, required)
    Pagination metadata returned on every list response. `page` and `limit` echo the values used to build this page (defaults are applied when the request omits them). `total` and `total_pages` reflect the full result set after any filters are applied.
    Example: {"limit":20,"page":1,"total":42,"total_pages":3}

  - `meta.limit` (integer, required)
    Page size used to build this response.

  - `meta.page` (integer, required)
    Index of the page returned, starting at 1.

  - `meta.total` (integer, required)
    Total number of items matching the request across all pages.

  - `meta.total_pages` (integer, required)
    Total number of pages available at the current `limit`.

## Response 400:

  - `400` (unknown)
    Bad request (e.g., missing or invalid fields). Invalid text may be reported as address.label_invalid, address.meta_invalid, public_key.label_invalid, invoice.comment_invalid, invoice.metadata_invalid.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

  - `fields` (array)
    List of invalid fields in the request.

  - `fields.name` (string, required)
    The name of the invalid field.
    Example: max_len

  - `fields.reason` (string, required)
    Why this field is invalid.
    Example: 32

## Response 401:

  - `401` (unknown)
    Missing or invalid authentication credentials.

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 403:

  - `403` (unknown)
    Insufficient permissions.

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 503:

  - `503` (unknown)
    The operation is temporarily unavailable. Please try again later.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response default:

  - `default` (unknown)
    Unexpected error.

## Response default fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 400 examples:

  - `The request body contains malformed JSON` (unknown)

## Response 401 examples:

  - `The API service refused authentication` (unknown)

## Response 403 examples:

  - `The API key lacks the required permission` (unknown)

## Response 503 examples:

  - `The operation cannot be completed at present` (unknown)