Get Reveal Batch

Poll one reveal batch for found and pending emails.

GEThttps://api.foxreach.io/api/v1/lead-finder/reveals/{batch_id}

Requires an API key with the read scope.

Use the batchId returned by Reveal Emails. Lookups run in the background, so poll until pending is 0.

Path Parameters#

batch_idstringpathrequired

The batch identifier.

Response#

dataobject

The batch.

Show data

batchIdstring

Batch identifier.

revealsarray

One row per person.

Show reveals

idstring

Reveal identifier.

personIdstring

Provider person id.

firstNamestring

First name.

lastNamestring

Last name.

companystring

Company.

statusstring

pending, found, not_found or error.

emailstring

The email, once found.

certaintystring

Confidence in the email: ultra_sure, very_sure or probable.

failureReasonstring

Why nothing was found, if known.

leadIdstring

The active lead for this email, or null.

inLeadsboolean

Whether an active lead exists.

creditsChargedinteger

Credits charged for this row.

pendinginteger

Rows still looking.

foundinteger

Rows with an email.

notFoundinteger

Rows with no email.

errorsinteger

Rows that errored.

balanceinteger

Current credit balance.

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.

Request

curl -X GET "https://api.foxreach.io/api/v1/lead-finder/reveals/bat_abc123" \
  -H "X-API-Key: otr_your_key"

from foxreach import FoxReach

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

import { FoxReach } from "foxreach";

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

Response

{
  "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
  }
}

Was this page helpful?

View as MarkdownLast updated November 2, 2026