> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foxreach.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Leads

> Retrieve a paginated list of leads in your workspace.

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number (starts at 1).
</ParamField>

<ParamField query="pageSize" type="integer" default="50">
  Number of leads per page (1-100).
</ParamField>

<ParamField query="search" type="string">
  Search across email, first name, last name, and company.
</ParamField>

<ParamField query="status" type="string">
  Filter by lead status: `active`, `bounced`, `unsubscribed`, or `replied`.
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of lead objects.

  <Expandable title="Lead object">
    <ResponseField name="id" type="string">Unique lead identifier.</ResponseField>
    <ResponseField name="email" type="string">Lead's email address.</ResponseField>
    <ResponseField name="firstName" type="string">First name.</ResponseField>
    <ResponseField name="lastName" type="string">Last name.</ResponseField>
    <ResponseField name="company" type="string">Company name.</ResponseField>
    <ResponseField name="title" type="string">Job title.</ResponseField>
    <ResponseField name="phone" type="string">Phone number.</ResponseField>
    <ResponseField name="linkedinUrl" type="string">LinkedIn profile URL.</ResponseField>
    <ResponseField name="website" type="string">Website URL.</ResponseField>
    <ResponseField name="customFields" type="object">Custom key-value fields.</ResponseField>
    <ResponseField name="notes" type="string">Freeform notes.</ResponseField>
    <ResponseField name="source" type="string">How the lead was created (e.g., `api`, `csv_import`, `manual`).</ResponseField>
    <ResponseField name="status" type="string">Lead status.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata.

  <Expandable title="Meta object">
    <ResponseField name="page" type="integer">Current page number.</ResponseField>
    <ResponseField name="pageSize" type="integer">Items per page.</ResponseField>
    <ResponseField name="total" type="integer">Total number of leads.</ResponseField>
    <ResponseField name="totalPages" type="integer">Total number of pages.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.foxreach.io/api/v1/leads?page=1&pageSize=20&search=acme" \
    -H "X-API-Key: otr_your_key"
  ```

  ```python Python SDK theme={null}
  from foxreach import FoxReach

  client = FoxReach(api_key="otr_your_key")

  leads = client.leads.list(page=1, page_size=20, search="acme")
  ```

  ```typescript TypeScript SDK theme={null}
  import { FoxReach } from "foxreach";

  const client = new FoxReach({ apiKey: "otr_your_key" });

  const leads = await client.leads.list({ page: 1, pageSize: 20, search: "acme" });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "cld_abc123",
        "email": "john@acme.com",
        "firstName": "John",
        "lastName": "Doe",
        "company": "Acme Inc",
        "title": "VP of Sales",
        "phone": "+1-555-0100",
        "linkedinUrl": "https://linkedin.com/in/johndoe",
        "website": "https://acme.com",
        "customFields": { "industry": "SaaS" },
        "notes": null,
        "source": "csv_import",
        "status": "active",
        "lastContactedAt": null,
        "createdAt": "2025-01-15T10:30:00",
        "updatedAt": "2025-01-15T10:30:00"
      }
    ],
    "meta": {
      "page": 1,
      "pageSize": 20,
      "total": 1,
      "totalPages": 1
    }
  }
  ```
</ResponseExample>

## 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).