# Enrich Company
Source: https://docs.captaindata.com/v1/api/companies/enrich

v1/api/openapi.json get /companies/enrich
Get comprehensive company information from a LinkedIn company URL.

<Info>
  This operation costs **1 credit**.

  **Coming Soon:** We're working on adding the ability to enrich company information based on domain names (e.g., `example.com`) instead of requiring a LinkedIn Profile URL.
</Info>

<Warning>
  LinkedIn URLs must be valid company URLs. Use [Find Company](/v1/api/companies/find) to get valid LinkedIn URLs from company names.
</Warning>


# Find Company
Source: https://docs.captaindata.com/v1/api/companies/find

v1/api/openapi.json get /companies/find
This operation allows you to find a single company based on some search criteria like its `company_name` or `domain`.

<Info>
  This operation costs **2 credits**.
</Info>


# Find Company Employees
Source: https://docs.captaindata.com/v1/api/companies/find-employees

v1/api/openapi.json get /companies/{company_uid}/employees
Retrieve a list of employees for a specific company using the company's UID.

<Info>
  This operation costs **1 credit per request + 1 credits per result**. A full page of 25 results typically consumes 26 credits (1 + 25).
</Info>

<Warning>
  This endpoint requires a valid company UID obtained from the [Find Company](/v1/api/companies/find) or [Search Companies](/v1/api/companies/search) endpoints.
</Warning>

<Info>
  The company\_uid is Captain Data's unique company identifier, which is compatible with the numerical LinkedIn company page ID (same as Sales Navigator ID). Note that the LinkedIn ID is immutable.
</Info>

<Info>
  This endpoint allows you to search for the current company's employees using Sales Navigator compatible filter queries.
</Info>

Copy the query string from a Sales Navigator people search URL and use it as the `query` parameter.

**Example:** `(keywords%3Aceo)`

<Warning>
  Not all Sales Navigator filters are compatible. Account-specific filters cannot be used.
</Warning>

<Info>
  `X-Pagination-Next` and `X-Pagination-Previous` headers may be included in
  the response to provide full URLs for the next or previous pages. **Always use
  these URLs as-is** — they contain the cursor needed for pagination. Cursors
  expire after **24 hours**; if expired, restart pagination from the beginning.
</Info>


# Search Companies
Source: https://docs.captaindata.com/v1/api/companies/search

v1/api/openapi.json get /companies/search
Search and discover companies based on a search query.

<Info>
  This endpoint allows you to search for companies using Sales Navigator compatible search queries.

  **Credit Cost:** 1 credit per request + 1 credits per result. A full page of 25 results typically consumes 6 credits (1 + 25).
</Info>

Copy the query string from a Sales Navigator company search URL and use it as the `query` parameter.

**Example:** `(keywords%3Aai)`

<Warning>
  Not all Sales Navigator filters are compatible. Account-specific filters cannot be used.
</Warning>


# Get People Licenses & Certifications
Source: https://docs.captaindata.com/v1/api/people/certifications

v1/api/openapi.json get /people/certifications
Retrieve licenses and certifications from a LinkedIn profile.

<Info>
  This endpoint allows you to retrieve a person's licenses and certifications.

  **Credit Cost:** 1 credit per request + 0.05 credits per result. A full page
  of 20 results typically consumes 2 credits (1 + 20 × 0.05).
</Info>

Provide either a LinkedIn profile URL or a Captain Data people UID.

<Warning>
  You must provide at least one of `li_profile_url` or `people_uid`.
</Warning>

<Info>
  `X-Pagination-Next` and `X-Pagination-Previous` headers may be included in
  the response to provide full URLs for the next or previous pages. **Always use
  these URLs as-is** — they contain the cursor needed for pagination. Cursors
  expire after **24 hours**; if expired, restart pagination from the beginning.
</Info>


# Enrich People
Source: https://docs.captaindata.com/v1/api/people/enrich

v1/api/openapi.json get /people/enrich
Get comprehensive profile information from a LinkedIn profile URL.

<Info>
  This operation costs **1 credit**. Using `full_enrich` set to `true` costs **2 credits**.
</Info>

**Full enrichment (2 credits) adds:**

* Detailed experiences, skills, education, languages
* Work history, volunteer experiences, connections count
* Past companies, job time periods, open to work status

With `full_enrich` set to `true`, the response includes **at most** the **5 most recent** experience entries, **2 most recent** skills, and **2 most recent** education entries.

<Warning>
  LinkedIn URLs must be valid profile URLs. Use [Find People](/v1/api/people/find) to get valid LinkedIn URLs from names.
</Warning>


# Get People Experiences
Source: https://docs.captaindata.com/v1/api/people/experiences

v1/api/openapi.json get /people/experiences
Retrieve the complete work experience history of a LinkedIn profile.

<Info>
  This endpoint allows you to retrieve a person's complete work experience
  history.

  **Credit Cost:** 1 credit per request + 0.05 credits per result.
</Info>

Provide either a LinkedIn profile URL or a Captain Data people UID.

<Warning>
  You must provide at least one of `li_profile_url` or `people_uid`.
</Warning>


# Find People
Source: https://docs.captaindata.com/v1/api/people/find

v1/api/openapi.json get /people/find
This operation allows you to find people based on search criteria. You can search by `full_name` alone, or combine it with `company_name` for more accurate results. The system automatically treats searches as exact phrase matches.

<Info>
  This operation costs **2 credits**.

  **Search accuracy tips:**

  * **Full Name only**: Basic search that may return multiple results for common names
  * **Full Name + Company Name**: Significantly increases the accuracy of finding the correct person by narrowing down the search scope
  * The system automatically treats your input as exact phrase matches (no need to add quotes)
  * Example: `John Smith` and `Acme Corporation` for precise results
</Info>

<Warning>
  This endpoint returns limited profile information (UID, LinkedIn profile URL, and LinkedIn profile ID). For detailed profile data, use the [Enrich People](/v1/api/people/enrich) endpoint.
</Warning>


# Search People
Source: https://docs.captaindata.com/v1/api/people/search

v1/api/openapi.json get /people/search
Search and discover people based on a search query.

<Info>
  This endpoint allows you to search for people using Sales Navigator compatible search queries.

  **Credit Cost:** 1 credit per request + 1 credits per result. A full page of 25 results typically consumes 26 credits (1 + 25).
</Info>

Copy the query string from a Sales Navigator people search URL and use it as the `query` parameter.

**Example:** `(keywords%3Aceo)`

<Warning>
  Not all Sales Navigator filters are compatible. Account-specific filters cannot be used.
</Warning>


# Get People Skills
Source: https://docs.captaindata.com/v1/api/people/skills

v1/api/openapi.json get /people/skills
Retrieve the complete list of skills from a LinkedIn profile.

<Info>
  This endpoint allows you to retrieve a person's complete list of skills.

  **Credit Cost:** 1 credit per request + 0.05 credits per result.
</Info>

Provide either a LinkedIn profile URL or a Captain Data people UID.

<Warning>
  You must provide at least one of `li_profile_url` or `people_uid`.
</Warning>


# Quotas
Source: https://docs.captaindata.com/v1/api/quotas

v1/api/openapi-core.json get /quotas
Get Workspace quota

## Use Cases

* **Monitor API Usage**: Track your credit consumption to avoid hitting limits and ensure uninterrupted service
* **Manage Billing**: Monitor your billing cycle and plan details for better cost management
* **Optimize Performance**: Analyze usage patterns to determine if you need to upgrade your plan


# Product Updates
Source: https://docs.captaindata.com/v1/changelog/overview

New updates and improvements!

<Update label="May 28th, 2026" description="Find Company — domain parameter">
  ### Find Company — find a company by domain

  **Affected endpoint:** [Find Company](/v1/api/companies/find)

  You can now find a company by passing its **`domain`** (for example `example.com`) instead of **`company_name`**. Provide one or the other — combining both in the same request is not supported.
</Update>

<Update label="April 1st, 2026" description="People Search — clearer errors">
  ### People Search — clearer errors about the source

  **Affected endpoint:** [People Search](/v1/api/people/search)

  Error responses from **People Search** are now **clearer about where the failure comes from**
</Update>

<Update label="March 20th, 2026" description="Sales Navigator pagination & cursor headers">
  ### Sales Navigator search — long queries and pagination headers

  **Pagination update:**\
  Legacy **`X-Pagination-Next`**/**`Previous`** headers (long URLs) are deprecated—migrate to **cursor-based pagination** (**`X-Cursor-Next`**/**`Previous`**). For long Sales Navigator queries, if URL headers are too larg (> 8Kb), the API now returns the cursor headers. Use whichever header is present for paging; cursor fallback is reliable and documented.
</Update>

<Update label="March 12th, 2026" description="Pricing display fixes">
  ### Pricing display fixes shipped

  We've shipped **pricing display fixes** impacting **plans**, **discounts**, and **totals** across the platform. You should now see consistent and correct pricing information wherever it is shown.

  ### API schema: headline deprecated, renamed to summary

  In the OpenAPI spec, the field **`headline`** has been renamed to **`summary`** in two schemas: **profile** and **person/employee-like** objects. **`headline`** is now **deprecated**; please use **`summary`** in new integrations.

  ### List endpoints: limit parameter maximum increased to 100

  The **`limit`** query parameter maximum has been increased from **20** to **100** (default remains 10) on the following list endpoints:

  * **[Get run callbacks](/v1/api/runs/callbacks)** — `GET /runs/callbacks`
  * **[List runs](/v1/api/runs)** — `GET /runs`
  * **[List schedules](/v1/api/schedules)** — `GET /schedules`
</Update>

<Update label="February 19th, 2026" description="Billing, MCP & error handling">
  ### Next billed amount reflects subscription discounts

  The **next billed amount** shown on the platform now includes any **discount applied to your subscription**, so you see the actual amount you'll be charged on the next invoice.

  ### MCP configuration examples — copy-paste ready

  We fixed the MCP (Model Context Protocol) configuration examples on the new Captain Data website so they are **copy-paste ready**. This reduces setup friction for customers exploring MCP usage.

  ### Improved error handling before returning to users

  We've reduced error risk by improving **internal error management** before errors are returned to the user. Errors are now processed and normalized internally first, leading to clearer and more consistent API responses.
</Update>

<Update label="January 28th, 2026" description="Find Company Employees filters & Find People error">
  ### Find Company Employees — Sales Navigator filter support

  **Affected endpoint:** [Find Company Employees](/v1/api/companies/find-employees)

  You can now reuse a **Sales Navigator People Search** (filters and keywords) and apply it to a company's employees. Pass the raw `query` parameter from a Sales Navigator people search URL to filter results (e.g. by current title, seniority, geography). The API merges these filters with the forced company context.

  See [Find Company Employees](/v1/api/companies/find-employees) for how to use the `query` parameter.

  ### Find People — Clear error when no unique result

  **Affected endpoint:** [Find People](/v1/api/people/find)

  When no unique result is found, the endpoint now returns a **clear and concise error** instead of an empty array. This makes it easier to distinguish "no match" from other issues and to handle the case explicitly in your integration.
</Update>

<Update label="January 15th, 2026" description="Cursor-based Pagination">
  ### Improved Pagination: Cursor-based

  **Affected endpoints:** All search endpoints ([People Search](/v1/api/people/search), [Companies Search](/v1/api/companies/search), [Find Company Employees](/v1/api/companies/find-employees))

  We've improved pagination across all search endpoints by transitioning to **cursor-based pagination**.

  **What's new:**

  * Pagination now uses the `cursor` parameter obtained from the `X-Pagination-Next` response header
  * Cursors are valid for **24 hours**, providing more flexibility for long-running integrations
  * More reliable and consistent results when paginating through large datasets

  **Breaking change:**

  * The `page` parameter has been **removed** — use cursor-based pagination instead

  **How to migrate:**

  1. Make your initial request without any pagination parameter
  2. Use the full URL from the `X-Pagination-Next` response header for subsequent requests
  3. Continue until `X-Pagination-Next` is no longer present

  See the updated [Pagination guide](/v1/pagination) for details.
</Update>

<Update label="January 9th, 2026" description="v3 Sunset & Bug Fix">
  ### 🌅 Captain Data v3 – End of Life

  Captain Data v3 has been officially sunset. All v3 features and endpoints are no longer available.

  We encourage all users to migrate to the [v1 API](/v1/introduction) for the latest capabilities and ongoing support.

  ### 🐛 Fix: Find People – Improved Profile Matching

  **Affected endpoint:** [`Find People`](/v1/api/people/find)

  We fixed an issue where the `Find People` endpoint could return non-unique or incorrect profiles. This update improves:

  * Deduplication of results
  * Accuracy of profile matching against your query
  * Overall result quality and reliability

  The endpoint now correctly returns only unique and relevant profiles matching your query.
</Update>

<Update label="v1.0 is here!" description="v1.0 – Public Release">
  ### 🚀 New Captain Data v1 – Official Public Release

  The new Captain Data is finally here! It makes it easy to get qualified, fresh and high-quality data about people and companies.

  You can now sign-up and start your journey on [https://app.captaindata.com](https://app.captaindata.com), following the simple [API documentation](/v1/introduction).

  You'll be able to:

  * Get enriched data about [people](/v1/api/people/enrich) and [companies](/v1/api/companies/enrich)
  * Find [people](/v1/api/people/find) and [companies](/v1/api/companies/find) based on generic informations
  * Search for [people (leads)](/v1/api/people/search) and [companies (accounts)](/v1/api/companies/search) based on Sales Navigator compatible queries
</Update>

<Update label="Planned for October 15th" description="v1.0 – Public Release">
  ### 🚀 New Captain Data v1 – Public Release

  The new Captain Data will be publicly available on October 15th and will make it easy to get qualified, fresh and high-quality data about people and companies.

  Get ready to get started at [https://app.captaindata.com](https://app.captaindata.com), following the simple [API documentation](/v1/introduction).
</Update>


# Error Reference
Source: https://docs.captaindata.com/v1/error-reference

Complete reference for all error codes, HTTP status codes, and troubleshooting guidance for the Captain Data API.

This page provides a comprehensive reference for understanding and handling errors across the Captain Data API.

***

## Quick Reference Table

| Status Code | Category   | Retry?                 | What to Do                                               |
| ----------- | ---------- | ---------------------- | -------------------------------------------------------- |
| `200`       | Success    | —                      | Process the response data                                |
| `400`       | Input      | No — fix input         | Check `error_label` and `message`, then fix your request |
| `401`       | Auth       | No — fix API key       | Verify your `X-API-Key` header                           |
| `403`       | Access     | No — check permissions | Verify account permissions                               |
| `404`       | Not Found  | No                     | Resource doesn't exist — no action needed                |
| `429`       | Rate Limit | Yes — with backoff     | Wait for `Retry-After` header value, then retry          |
| `500`       | Server     | Yes — with backoff     | Retry after a short delay                                |

***

## Error Response Structure

The API uses a consistent error response format across all endpoints. When an error occurs, you'll receive a response with the following structure:

```json theme={null}
{
  "error_label": "INVALID_INPUT",
  "error_scope": "input",
  "error_ref": "ERR-12345",
  "message": "The provided input is invalid. Please check your request and try again.",
  "status_code": 400,
  "params": {}
}
```

Each error response includes:

* `error_label`: A machine-readable identifier for the error type
* `error_scope`: Indicates which part of the request caused the error (e.g., "input", "auth", "server")
* `error_ref`: A unique reference code for tracking and debugging
* `message`: A human-readable description of the error
* `status_code`: The HTTP status code
* `params`: Additional error parameters (if any)

***

## Understanding Error Scopes

Every error response includes an `error_scope` field that indicates what caused the error:

| Scope    | Description                           | Typical Action                           |
| -------- | ------------------------------------- | ---------------------------------------- |
| `input`  | The input data provided is invalid    | Fix the input format or value            |
| `param`  | A parameter in the request is invalid | Check parameter requirements in the docs |
| `auth`   | Authentication or authorization issue | Verify your API key and permissions      |
| `server` | Server-side error                     | Retry with backoff, or contact support   |

***

## Handling Rate Limit Errors (429)

When you exceed rate limits, you'll receive a `429 Too Many Requests` response. Use the `Retry-After` header to know when to retry.

**Example Implementation:**

```javascript theme={null}
async function callWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        // Use Retry-After header if available, otherwise exponential backoff
        const retryAfter = error.headers['retry-after'];
        const delay = retryAfter 
          ? parseInt(retryAfter) * 1000 
          : Math.min(1000 * Math.pow(2, attempt), 30000);
        
        console.log(`Rate limited. Waiting ${delay}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error; // Non-retryable error
      }
    }
  }
  throw new Error('Max retries exceeded');
}
```

<Tip>
  For detailed rate limit information by plan tier, see our [Rate Limits documentation](/v1/rate-limits).
</Tip>

***

## Error Categories

### Input & Validation Errors (400)

These errors occur when your request contains invalid data. **Do not retry** — fix the input first.

<AccordionGroup>
  <Accordion title="INVALID_INPUT" icon="circle-xmark">
    **Description**: The input data is invalid or incorrectly formatted.

    **Common Causes**:

    * Invalid URL format
    * Missing required identifiers
    * Malformed query parameters

    **Resolution**: Check the `message` field for details, then verify your input against the endpoint's documentation.
  </Accordion>

  <Accordion title="BAD_PARAMETERS" icon="sliders">
    **Description**: One or more parameters in the request are invalid.

    **Common Causes**:

    * Parameter value out of allowed range
    * Incompatible parameter combinations
    * Wrong data type for a parameter

    **Resolution**: Review parameter constraints in the endpoint documentation.
  </Accordion>
</AccordionGroup>

### Authentication & Access Errors (401, 403)

These errors indicate permission or authentication issues.

<AccordionGroup>
  <Accordion title="UNAUTHORIZED (401)" icon="key">
    **Description**: Your API key is invalid or missing.

    **Common Causes**:

    * Missing `X-API-Key` header
    * Invalid or expired API key
    * Typo in the API key

    **Resolution**: Verify your API key in [Developer Settings](https://app.captaindata.com/developers).
  </Accordion>

  <Accordion title="FORBIDDEN (403)" icon="lock">
    **Description**: You don't have access to this resource.

    **Common Causes**:

    * Insufficient plan permissions
    * Resource restricted to specific accounts

    **Resolution**: Check your subscription plan includes access to this endpoint.
  </Accordion>
</AccordionGroup>

### Not Found Errors (404)

These errors indicate the requested resource doesn't exist.

<AccordionGroup>
  <Accordion title="NOT_FOUND" icon="magnifying-glass">
    **Description**: The resource you requested doesn't exist or is no longer available.

    **Common Causes**:

    * Profile has been deleted or deactivated
    * Company page no longer exists
    * Invalid identifier (typo in URL or ID)

    **Resolution**: Verify the resource URL/ID is correct. If valid, the resource may have been removed — **no retry needed**.
  </Accordion>

  <Accordion title="NO_RESULT" icon="inbox">
    **Description**: The query returned no results.

    **Common Causes**:

    * Search criteria too narrow
    * No matching data found

    **Resolution**: Treat as an empty result set. Consider broadening your search criteria.
  </Accordion>
</AccordionGroup>

### Server Errors (500, 503)

These errors indicate something went wrong on our end.

<AccordionGroup>
  <Accordion title="INTERNAL_ERROR (500)" icon="server">
    **Description**: An unexpected server error occurred.

    **Resolution**: Retry with exponential backoff. If persistent, contact [support@captaindata.com](mailto:support@captaindata.com) with the `error_ref` value.
  </Accordion>

  <Accordion title="SERVICE_UNAVAILABLE (503)" icon="clock">
    **Description**: The service is temporarily unavailable.

    **Resolution**: Wait a few minutes and retry. This is typically a transient issue.
  </Accordion>
</AccordionGroup>

***

## Best Practices

1. **Always check `error_label`**: Use this field to programmatically handle different error types.

2. **Log the `error_ref`**: This unique reference helps our support team investigate issues quickly.

3. **Implement exponential backoff**: For retryable errors (429, 500, 503), wait progressively longer between retries.

4. **Don't retry input errors**: 400-level errors (except 429) require fixing your request, not retrying.

<Info>
  If you encounter persistent errors or need help debugging, contact [support@captaindata.com](mailto:support@captaindata.com) with the `error_ref` from your error response.
</Info>


# Introduction
Source: https://docs.captaindata.com/v1/introduction

API Reference Version 1

<Note>
  Welcome to the new Captain Data API v1, which allows you to **get qualified, fresh and high-quality data about people and companies.**
  If you encounter any issues using this API, feel free to reach out at
  [support@captaindata.com](mailto:support@captaindata.com).
</Note>

<Card title="Get your API Key" icon="key" href="https://app.captaindata.com/developers">
  Go to Developer Settings to get your API key and start using the API.
</Card>

<Card title="Use our documentation MCP" icon="gem" href="https://docs.captaindata.com/mcp">
  Add Captain Data Documentation to your AI assistant or IDE thanks to our Model Context Protocol server. Best advices directly from the documentation into your IDE !
</Card>

## Authentication

To authorize requests, you need to add the following header `X-API-Key: <your_api_key>` to all API requests (case insensitive).
Here’s an example of a request to the API:

```bash theme={null}
curl --location 'https://api.captaindata.com/v1/quotas' \
--header 'X-API-Key: <your_api_key>'
```

All subsequent examples will use this header as part of the request.

To get your API Key, go to [Developer Settings](https://app.captaindata.com/developers) and copy the appropriate values.

<Tip>
  Each user of your workspace has their own unique API Key that is tied to their account. API Keys
  are not shared across the workspace.
</Tip>

## Playground

Each API endpoint has an interactive playground where you can test requests directly.

## Pagination

Some endpoints return paginated results. To handle pagination the best possible way, we've got you covered with a simple and efficient mechanism and a full guide to explain it in the [Handle Pagination documentation](/v1/pagination).

## Rate Limits

The API is rate limited to manage the load on our servers. You can find detailed information about the rate limits in the [Rate Limits documentation](/v1/rate-limits).

## Error Reference

For handling errors, check out our [Error Reference documentation](/v1/error-reference) which covers all HTTP status codes and how to handle them.

## Have Questions?

If you're exploring our doc you can also ask your AI tool thanks to our [MCP (Model Context Protocol)](https://docs.captaindata.com/mcp).


# Handle Pagination
Source: https://docs.captaindata.com/v1/pagination

Learn how to paginate search results effectively

Some operations return multiple pages of results, especially searches. This quick guide explains how to handle pagination effectively.

## Pagination Headers

Each response includes headers to help you navigate:

<ParamField type="string">
  Full URL to fetch the next page — **always use this URL as-is** for reliable pagination. Contains the cursor for cursor-based pagination.
</ParamField>

<ParamField type="string">
  Full URL to fetch the previous page — **use this URL as-is** for reliable pagination
</ParamField>

## Pagination Parameters

<ParamField type="string">
  Cursor value for cursor-based pagination. **Always obtain this from the `X-Pagination-Next` response header** — do not construct cursor values manually. Cursors expire after **24 hours**; if expired, restart pagination from the beginning.
</ParamField>

<ParamField type="number">
  Maximum number of items per page (read-only, varies by operation)
</ParamField>

<ParamField type="number">
  Page number to retrieve. **Removed as of January 15th, 2026** — use cursor-based pagination instead.
</ParamField>

## How to Paginate

<Tip>
  **Best practice:** Always follow the `X-Pagination-Next` header URL as-is. Stop when it's no longer present — you've reached the last page.
</Tip>

* Extract the cursor from the `X-Pagination-Next` response header
* Pass it as the `cursor` query parameter (or simply use the full URL from the header)
* Cursors are valid for **24 hours** — after that, you must restart from the beginning

### Pagination Example

<Steps>
  <Step title="1. Make the initial request">
    Start fetching the first page of results (no cursor needed).

    ```bash theme={null}
    curl -i --request GET \
      --url 'https://api.captaindata.com/v1/people/search?query=(keywords%3Aceo)' \
      --header 'X-API-Key: <your-api-key>'
    ```
  </Step>

  <Step title="2. Check the response headers">
    Examine the response headers to find pagination info:

    * `X-Pagination-Next`: URL for next page (includes cursor) or absent if last page
    * `X-Pagination-Previous`: URL for previous page or absent if first page
  </Step>

  <Step title="3. Fetch the next page">
    Use the full URL from `X-Pagination-Next`:

    ```bash theme={null}
    curl -i --request GET \
      --url 'https://api.captaindata.com/v1/people/search?query=(keywords%3Aceo)&cursor=eyJwYWdlIjoyLCJza...' \
      --header 'X-API-Key: <your-api-key>'
    ```
  </Step>

  <Step title="4. Continue until done">
    Repeat until the `X-Pagination-Next` header is **no longer present**, meaning you've reached the last page.
  </Step>
</Steps>

<Warning>
  Cursors expire after **24 hours**. If you receive an error indicating an invalid or expired cursor, you must restart pagination from the beginning (without a cursor).
</Warning>


# Rate Limits
Source: https://docs.captaindata.com/v1/rate-limits

Learn about rate limits, quotas, and best practices for managing API usage with Captain Data.

Captain Data implements rate limits to ensure fair usage and optimal performance for all users.
Understanding these limits helps you design efficient automations and avoid interruptions.

Rate limits are applied at multiple levels:

* **API Endpoints**: Per-minute limits on specific API calls
* **Daily Quotas**: Total daily usage limits based on your plan

<Tip>Each plan includes a daily quota that represents your total usage allowance. This quota is consumed by all API calls across your workspace.</Tip>

## Plan Tiers and Rate Limits

Your rate limits are determined by your plan tier, which is based on your monthly credit allocation:

| Plan Tier | Monthly Credits         | Max Requests/Second | Max Requests/Minute |
| --------- | ----------------------- | ------------------- | ------------------- |
| Trial     | Up to 1,000             | 1                   | 60                  |
| Bronze    | 1 - 10,000              | 2                   | 120                 |
| Silver    | 10,001 - 100,000        | 10                  | 600                 |
| Gold      | 100,001 - 500,000       | 10                  | 600                 |
| Platinum  | 500,001 - 2,000,000     | 20                  | 1,200               |
| Diamond   | 2,000,001 - 20,000,000  | 20                  | 1,200               |
| Titanium  | 20,000,001 - 50,000,000 | 40                  | 2,400               |

<Tip>Check your [subscription page](https://app.captaindata.com/plans) in Captain Data to see your current plan tier and monthly credit allocation.</Tip>

### Capacity Examples

Assuming an average request duration of 2-3 seconds:

| Plan Tier          | Estimated Daily Capacity | Example Use Case       |
| ------------------ | ------------------------ | ---------------------- |
| Trial              | \~86,400 requests/day    | Small-scale testing    |
| Bronze             | \~172,800 requests/day   | Individual prospecting |
| Silver / Gold      | \~864,000 requests/day   | Team sales operations  |
| Platinum / Diamond | \~1,728,000 requests/day | Large-scale enrichment |
| Titanium           | \~3,456,000 requests/day | Enterprise automation  |

**Example**: With a Silver or Gold tier plan (600 requests/minute), you can:

* Enrich \~864,000 people profiles per day
* Process \~36,000 profiles per hour
* Handle \~600 concurrent enrichment requests

### Quotas

Rate limits for quota and billing data retrieval via `/quotas`:

| Plan Tier | Max Requests/Second | Max Requests/Minute |
| --------- | ------------------- | ------------------- |
| Trial     | \< 1                | 5                   |
| Bronze    | \< 1                | 10                  |
| Silver    | 1                   | 50                  |
| Gold      | 1                   | 50                  |
| Platinum  | 1                   | 75                  |
| Diamond   | 1                   | 75                  |
| Titanium  | 2                   | 100                 |

## Best Practices

### Optimizing for Rate Limits

1. **Implement Exponential Backoff**: When you hit rate limits, wait before retrying with increasing delays.

2. **Monitor Your Usage**: Track your API consumption to stay within limits.

### Handling Rate Limit Errors

When you exceed rate limits, you'll receive a `429 Too Many Requests` response.

```json theme={null}
{
  "error": {
    "code": 429,
    "status": "Too Many Requests",
    "details": {
      "Retry-After": "60",
      "X-RateLimit-Limit": "2",
      "X-RateLimit-Reset": "1754402101",
      "X-RateLimit-Type": "/v1/people/enrich"
    },
    "message": "Rate limit exceeded (/v1/people/enrich)"
  }
}
```

<Info>This rate limit error response uses a different structure than our standard error format. For details on our typical error responses, see our [Error Reference](/v1/error-reference).</Info>

## Monitoring and Alerts

Track your rate limit usage through:

* API response headers
* Dashboard analytics
* Webhook notifications for quota warnings

## Getting Help

If you consistently hit rate limits or need higher limits:

1. **Review your implementation design** for optimization opportunities
2. **Consider upgrading your plan** for higher limits
3. **Contact support** for custom enterprise solutions

For detailed information about your current plan's limits, check your workspace dashboard or contact our support team.