---
title: "Get a batch verification request."
method: GET
path: "/v1/requests/{id}"
---

# Get a batch verification request.

`GET /v1/requests/{id}`

## Request

- Base URL: `https://api.bounceless.io`
- URL: `https://api.bounceless.io/v1/requests/{id}`
- Auth: API key in header `X-Api-Key`

Poll with bounded exponential backoff until request.state is terminal. finalized is the successful export-ready terminal. failed_validation, rejected_credit, cancelled, failed, expired, and purged are also terminal and require client handling; completed is transitional.

## Path parameters

- `id` string, uuid, required

## Response `200`

Request status.

- BatchRequest
  - `request` RequestDescriptor, required
    - `id` string, uuid, required
    - `mode` string, required
    - `state` 'received' | 'validating' | 'queued' | 'running' | 'retrying' | 'degraded' | 'paused' | 'completed' | 'finalized' | 'failed_validation' | 'rejected_credit' | 'cancelled' | 'failed' | 'expired' | 'purged', required
    - `partial` boolean
    - `finalized` boolean
    - `countsMayChange` boolean
    - `createdAt` string, date-time, required
  - `counters` Counters, required
  - `resultCounters` ResultCounters: Whole-list final result categories, returned by request detail; independent of search and pagination. Existing counters retain first-pass semantics.
    - `submittedCount` integer
    - `totalCount` integer
    - `validCount` integer
    - `catchAllCount` integer
    - `unknownCount` integer
    - `invalidCount` integer
    - `riskyCount` integer
    - `recheckCount` integer
    - `pendingCount` integer
    - `otherCount` integer
  - `summary` RequestSummary: Full-request aggregates, returned by GET /v1/requests/{id}. deliverableRate is omitted when no address has resolved.
    - `checkedCount` integer, required: Resolved addresses: valid, invalid, risky, catch_all and unknown.
    - `deliverableCount` integer, required
    - `deliverableRate` number: deliverableCount / checkedCount as a ratio, 4 decimals.
    - `recheckCount` integer, required: Rows across the whole request requiring another check (deferred or recheck_scheduled).
  - `replayed` boolean
  - `requestId` string, required

## Other responses

- `401`: Error response.
- `404`: Error response.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/bounceless/apis/bounceless-api.md) - [All operations](https://skmtc.dev/bounceless/apis/bounceless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bounceless/apis/bounceless-api/revisions/d80696082abb?raw)