# Get Reveal Batch

> Poll one reveal batch for found and pending emails.

Requires an API key with the `read` scope.

Use the `batchId` returned by [Reveal Emails](/api-reference/lead-finder/reveal-emails). Lookups run in the background, so poll until `pending` is 0.

## Path Parameters

<ParamField path="batch_id" type="string" required>
  The batch identifier.
</ParamField>

## Response

<ResponseField name="data" type="object">
  The batch.

  <Expandable title="data">
    <ResponseField name="batchId" type="string">Batch identifier.</ResponseField>
    <ResponseField name="reveals" type="array">
      One row per person.

      <Expandable title="reveals">
        <ResponseField name="id" type="string">Reveal identifier.</ResponseField>
        <ResponseField name="personId" type="string">Provider person id.</ResponseField>
        <ResponseField name="firstName" type="string">First name.</ResponseField>
        <ResponseField name="lastName" type="string">Last name.</ResponseField>
        <ResponseField name="company" type="string">Company.</ResponseField>
        <ResponseField name="status" type="string">`pending`, `found`, `not_found` or `error`.</ResponseField>
        <ResponseField name="email" type="string">The email, once found.</ResponseField>
        <ResponseField name="certainty" type="string">Confidence in the email: `ultra_sure`, `very_sure` or `probable`.</ResponseField>
        <ResponseField name="failureReason" type="string">Why nothing was found, if known.</ResponseField>
        <ResponseField name="leadId" type="string">The active lead for this email, or `null`.</ResponseField>
        <ResponseField name="inLeads" type="boolean">Whether an active lead exists.</ResponseField>
        <ResponseField name="creditsCharged" type="integer">Credits charged for this row.</ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="pending" type="integer">Rows still looking.</ResponseField>
    <ResponseField name="found" type="integer">Rows with an email.</ResponseField>
    <ResponseField name="notFound" type="integer">Rows with no email.</ResponseField>
    <ResponseField name="errors" type="integer">Rows that errored.</ResponseField>
    <ResponseField name="balance" type="integer">Current credit balance.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
```bash cURL
curl -X GET "https://api.foxreach.io/api/v1/lead-finder/reveals/bat_abc123" \
  -H "X-API-Key: otr_your_key"
```

```python Python SDK (beta)
from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
batch = client.lead_finder.get_reveal_batch("bat_abc123")
```

```typescript TypeScript SDK (beta)
import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const batch = await client.leadFinder.getRevealBatch("bat_abc123");
```
</RequestExample>

<ResponseExample>
```json
{
  "data": {
    "batchId": "bat_abc123",
    "reveals": [
      {
        "id": "rev_abc123",
        "personId": "per_abc123",
        "firstName": "Jane",
        "lastName": "Doe",
        "company": "Acme Inc",
        "status": "found",
        "email": "jane@acme.com",
        "certainty": "ultra_sure",
        "failureReason": null,
        "leadId": null,
        "inLeads": false,
        "creditsCharged": 1
      }
    ],
    "pending": 0,
    "found": 1,
    "notFound": 0,
    "errors": 0,
    "balance": 99
  }
}
```
</ResponseExample>

## Errors

| Status | Description |
|--------|-------------|
| `401` | Missing, invalid, revoked or expired API key |
| `403` | API key does not have the required scope: `read` |
| `404` | `Lead Finder is not enabled` while Lead Finder is switched off on this environment |
| `404` | `Batch not found`, or the batch belongs to another workspace |
| `503` | `Lead Finder is not configured` when it is enabled but has no data provider key |

## Rate Limit

- **100 requests per minute, per API key.** Fixed 60-second window.
- Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix epoch seconds).
- A `429` response includes a `Retry-After` header (seconds until the bucket resets).

For client-side patterns (`Retry-After`, exponential backoff, monitoring `X-RateLimit-Remaining`), see [Rate Limiting](/rate-limiting).