# List Reveals
> The workspace's reveal history for one month, newest first.
Requires an API key with the `read` scope.
## Query Parameters
Month as `YYYY-MM`, from 2020-01 to 2100-12. Defaults to the current month.
`found`, `returned` (not found or errored) or `pending`.
Substring match on first name, last name, email or company.
Page number, starting at 1.
Rows per page. Values above 100 are capped at 100.
## Response
One page of history.
The rows.
Reveal identifier. Use it as a `revealIds` entry.
Batch the reveal belongs to.
Provider person id.
First name.
Last name.
Job title.
Company.
Company domain.
LinkedIn URL.
`pending`, `found`, `not_found` or `error`.
The email, once found.
Confidence in the email: `ultra_sure`, `very_sure` or `probable`.
Why a reveal returned nothing or was refunded, for example `already_in_leads`.
The active lead for this email, or `null`.
Whether an active lead exists.
Credits charged for this row.
ISO 8601 timestamp.
ISO 8601 timestamp, or `null` while pending.
Campaign the reveal was made into, or `null`.
Where a found person is now: the campaign name, `Leads` or `Lead Finder only`. `null` otherwise.
Rows matching the filters.
Current page.
Rows per page.
Totals for the whole month, ignoring `status` and `q`: `month`, `reveals`, `found`, `notFound`, `pending`, `creditsUsed`, `inCampaign`.
```bash cURL
curl -X GET "https://api.foxreach.io/api/v1/lead-finder/reveals?month=2026-10&status=found" \
-H "X-API-Key: otr_your_key"
```
```python Python SDK (beta)
from foxreach import FoxReach
client = FoxReach(api_key="otr_your_key")
history = client.lead_finder.list_reveals(month="2026-10", status="found")
```
```typescript TypeScript SDK (beta)
import { FoxReach } from "foxreach";
const client = new FoxReach({ apiKey: "otr_your_key" });
const history = await client.leadFinder.listRevealBatches({ month: "2026-10", status: "found" });
```
```json
{
"data": {
"reveals": [
{
"id": "rev_abc123",
"batchId": "bat_abc123",
"personId": "per_abc123",
"firstName": "Jane",
"lastName": "Doe",
"title": "CTO",
"company": "Acme Inc",
"companyDomain": "acme.com",
"linkedinUrl": "https://www.linkedin.com/in/janedoe",
"status": "found",
"email": "jane@acme.com",
"certainty": "ultra_sure",
"failureReason": null,
"leadId": null,
"inLeads": false,
"creditsCharged": 1,
"createdAt": "2026-10-30T14:02:00",
"completedAt": "2026-10-30T14:02:09",
"campaignName": null,
"nowIn": "Lead Finder only"
}
],
"total": 1,
"page": 1,
"pageSize": 50,
"summary": {
"month": "2026-10",
"reveals": 1,
"found": 1,
"notFound": 0,
"pending": 0,
"creditsUsed": 1,
"inCampaign": 0
}
}
}
```
## 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 |
| `422` | `month must be YYYY-MM` or `status must be found, returned or pending` |
| `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).