---
title: "Retrieve Leads"
method: GET
path: "/v1/leads"
tags: ["Leads"]
---

# Retrieve Leads

`GET /v1/leads`

## Request

- Base URL: `https://api.leadboxer.com`
- URL: `https://api.leadboxer.com/v1/leads`
- Auth: API key in header `x-api-key`

Returns a list of leads in JSON format based on the provided filters and query parameters.

## Query parameters

- `site` string, required
- `search` string
- `limit` integer
- `locale` string
- `nextToken` string
- `criteriaTextFilter` string
- `criteriaNumberFilter` string
- `criteriaTimeFilter` string, required
- `criteriaFieldFilter` string
- `criteriaExitLinkFilter` string
- `criteriaLeadscoreFilter` integer
- `criteriaDisplayFilter` string
- `timeField` 'eventEsTimestamp' | 'first_session_unix_timestamp', required
- `usePresetExclusionList` 'use_id' | 'last_most_likely_company' | 'organizationName' | 'organizationDomain'
- `userId` integer
- `timeZone` string
- `sortBy` string

## Response `200`

OK

- GetAllResponse
  - `data` object[]
  - `metaData` object

## Other responses

- `400`: Bad Request: The request is invalid or malformed (missing/incorrect parameters).
- `402`: Payment Required: The client has exceeded credit limits.
- `403`: Forbidden: The authenticated user does not have permission to access this resource.
- `404`: Not Found: The requested resource does not exist.
- `409`: Conflict: The request could not be completed due to a resource state conflict.
- `429`: Too Many Requests: Rate limit exceeded. The client has sent too many requests in a given time period
- `500`: Interval Server Error: An unexpected error occurred on the server.

---

[API](https://skmtc.dev/leadboxer/apis/leadboxer-api.md) · [All operations](https://skmtc.dev/leadboxer/apis/leadboxer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/leadboxer/apis/leadboxer-api/revisions/34249b480395?raw)