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

# List Buyers

> Retrieve a paginated list of Buyers in your workspace.

Returns Buyers belonging to the workspace associated with your API key.

```text theme={null}
GET /v1/buyers
```

## Request

```text theme={null}
curl "https://api.1eye.ai/v1/buyers" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

## Query parameters

| Parameter        | Type      | Description                                                           |
| :--------------- | :-------- | :-------------------------------------------------------------------- |
| `limit`          | integer   | Number of Buyers to return. Default: `100`. Maximum: `1000`.          |
| `cursor`         | string    | Cursor returned by the previous request for retrieving the next page. |
| `created_after`  | timestamp | Return Buyers created at or after this timestamp.                     |
| `created_before` | timestamp | Return Buyers created before this timestamp.                          |
| `sort_by`        | string    | Field used to sort results. GET buyers only support `created_at`.     |
| `sort_order`     | string    | Sort direction. Supported values: `asc`, `desc`.                      |

## Filter by creation time

Use `created_after` and `created_before` to filter Buyers by when they were created.

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?created_after=2026-09-01T00:00:00Z&created_before=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

Time filters use inclusive-start and exclusive-end semantics:

```text theme={null}
created_after  → created_at >= value
created_before → created_at < value
```

Timestamps use UTC in ISO 8601 format:

```text theme={null}
YYYY-MM-DDTHH:mm:ssZ
```

## Sort Buyers

GET buyers only support `created_at`.

Newest Buyers first:

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

Oldest Buyers first:

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?sort_by=created_at&sort_order=asc" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

By default, Buyers are returned in:

```text theme={null}
created_at DESC
id DESC
```

The Buyer ID is automatically used as a deterministic tie-breaker and does not need to be included in `sort_by`.

## Pagination

Use `limit` to control the number of Buyers returned in each request.

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?limit=100" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

If additional results are available, the response includes a `next_cursor`.

Pass that value using the `cursor` parameter to retrieve the next page:

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?limit=100&cursor=eyJ..." \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

Continue requesting pages until `next_cursor` is `null`.

## Example request

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?limit=100&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

## Response

A successful request returns Buyer objects in `data`.

The example below shows one Buyer for readability.

```text theme={null}
{
  "total": 1245,
  "data": [
    {
      "id": "buy_123456789012345678",
      "client_id": "wor_123456789012345678",
      "contact_info": {
        "name": {
          "first": "Jane",
          "middle": "",
          "last": "Doe"
        },
        "role": {
          "title": "VP of Sales",
          "function": "sales",
          "seniority": "vp",
          "start_date": ""
        },
        "email": {
          "work": "jane@example.com",
          "is_valid": true
        },
        "phone": {
          "mobile": "+14155550123",
          "is_valid": true
        },
        "social": {
          "linkedin": "https://www.linkedin.com/in/janedoe",
          "twitter": "",
          "github": "",
          "facebook": "",
          "linkedin_followers": 1200,
          "is_linkedin_valid": true
        },
        "location": {
          "city": "San Francisco",
          "state": "California",
          "country": "United States",
          "postal_code": "94105"
        },
        "photo_url": "https://example.com/photo.jpg",
        "is_persona": true,
        "persona_id": "per_123456789012345678",
        "persona_name": "Sales",
        "persona_reasoning": "The contact's role and seniority align with the Sales persona."
      },
      "company_info": {
        "name": "Acme",
        "website": "acme.com",
        "logo": "https://example.com/logo.png",
        "industries": [
          "computer software",
          "information technology & services"
        ],
        "employee_count": 250,
        "founded_year": 2018,
        "annual_revenue": 50000000,
        "company_type": "private",
        "social": {
          "linkedin": "https://www.linkedin.com/company/acme",
          "twitter": "https://twitter.com/acme",
          "facebook": ""
        },
        "location": {
          "street_address": "123 Market St",
          "city": "San Francisco",
          "state": "California",
          "postal_code": "94105",
          "country": "United States"
        },
        "total_funding": 25000000,
        "latest_funding_stage": "series_b",
        "latest_funding_round_date": "2026-06-15",
        "is_icp": true,
        "icp_id": "icp_123456789012345678",
        "icp_name": "B2B Scaleup",
        "icp_reasoning": "The company matches the workspace's B2B Scaleup ICP."
      },
      "hems": [
        {
          "type": "md5",
          "value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
      ],
      "target_lists": [
        {
          "id": "lis_123456789012345678",
          "name": "Website Visitors"
        }
      ],
      "signal_count": {
        "total": 6,
        "website": 3,
        "market": 2,
        "linkedin": 1
      },
      "attribution": {
        "type": "paid",
        "source": "google_ads",
        "source_name": "Google Ads",
        "source_logo": "https://example.com/google-ads.png"
      },
      "first_signal_id": "sig_123456789012345678",
      "first_signal_type": "website",
      "first_signal_trigger": "visited_page",
      "last_signal_id": "sig_987654321098765432",
      "last_signal_type": "linkedin",
      "last_signal_trigger": "reacted_post",
      "created_at": "2026-09-20T18:27:36Z",
      "updated_at": "2026-09-25T19:03:28Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJ..."
  }
}
```

The Buyer object includes contact and company information, ICP and Persona evaluation, Target Lists, Signal counts, attribution, and first and last Signal details. The current API response uses these fields and nested structures.

When there are no additional pages:

```text theme={null}
{
  "pagination": {
    "next_cursor": null
  }
}
```

## Errors

| Status | Error Code             | Description                                                    |
| :----- | :--------------------- | :------------------------------------------------------------- |
| `400`  | `invalid_parameter`    | An unsupported or invalid query parameter was provided         |
| `400`  | `invalid_cursor`       | The pagination cursor is invalid or does not match the request |
| `401`  | `authentication_error` | The API key is missing, invalid, or revoked                    |
| `429`  | `rate_limit_exceeded`  | The workspace has exceeded an API rate limit                   |
| `500`  | `internal_error`       | An unexpected server error occurred                            |
| `503`  | `service_unavailable`  | The API is temporarily unavailable                             |