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

# Credits vs limits

> Enrichment credits are a paid balance you spend. Plan limits are quotas included in your plan. They are tracked, exhausted, and refilled differently.

Pipecorn meters usage with two separate mechanisms that are easy to confuse,
partly because the `GET /credits` response uses the word "credits" for both.
This page tells them apart so you know which one a request draws on, which one
an error is about, and what actually unblocks you.

> [!NOTE]
>
> **One-line version.** A **credit** is a paid unit you spend on enrichment
> (emails, phones, company and people data). A **limit** is a quota bundled
> with your plan that caps how many profiles or companies you can extract per
> day or month. Buying credits never raises a limit, and a limit resetting
> never adds credits.

## Side by side

| | Enrichment credits | Plan limits |
| - | - | - |
| What it is | A prepaid balance owned by your workspace | Daily and monthly quotas included in your plan |
| What draws on it | Enrichment: waterfall email and phone, account and people enrichment, hiring and tech-stack lookups | Extraction: pulling people profiles or importing companies from a search, a Sales Navigator URL, or a post |
| Unit | Credits per result (for example 3 per email, 30 per phone, 1 per enriched company) | One profile or one company per unit |
| How it goes down | Spent per successful result. A lookup that resolves nothing costs nothing | Consumed per extracted profile or imported company |
| How it goes back up | Buy credits, or wait for your plan renewal to add the plan's monthly allocation | Resets automatically: daily quotas every day, the monthly company quota every month |
| How to get more | [Top up](https://app.pipecorn.com/settings/subscriptions/credits) at any time | Upgrade your plan, or contact support |
| Where to check | `credits.enrichment` in [`GET /credits`](https://docs.pipecorn.com/api-reference/endpoints/miscellaneous/account-credits), or [`GET /credits_consumption`](https://docs.pipecorn.com/api-reference/endpoints/miscellaneous/credit-consumption) for a date range | `credits.daily_profile_scraping`, `credits.daily_company_import`, `credits.monthly_company_import` (remaining) and `limits.*` (ceiling) in `GET /credits` |
| Error when exhausted | `402 Payment Required`, `code: "insufficient_credits"`, with a `top_up_url` | `422 Unprocessable Entity`, message `"Can't proceed with the request. Plan limit reached."`. On the Scale plan, `202 Accepted` with `status: "queued"` instead: the request waits for the reset |

Preview endpoints (`/leads/advanced_search/preview`, `/accounts/search/preview`,
`/intents/accounts/stack/preview`) draw on neither. They are free and never
return either error.

## Enrichment credits

Credits are the paid resource. Every endpoint that returns enriched data checks
your balance before doing any work and charges only for what it actually
returns:

* [Waterfall enrichment](https://docs.pipecorn.com/api-reference/endpoints/enrichments/single.md): **3 credits** per email, **9 credits** per personal email, **30 credits** per phone
* [Enrich account](https://docs.pipecorn.com/api-reference/endpoints/accounts/single.md) and
  [Enrich people](https://docs.pipecorn.com/api-reference/endpoints/leads/single.md): **1 credit** per
  resolved company or person
* [Reverse email lookup](https://docs.pipecorn.com/api-reference/endpoints/leads/reverse_email_lookup.md):
  **1 credit**, and [reverse phone lookup](https://docs.pipecorn.com/api-reference/endpoints/leads/reverse_phone_lookup.md):
  **30 credits**, per person found. A lookup that matches nobody is free
* [Company hiring](https://docs.pipecorn.com/api-reference/endpoints/accounts/company-hiring.md): **1 credit**
  per job returned
* [Company stack](https://docs.pipecorn.com/api-reference/endpoints/accounts/company-stack.md),
  [hiring intent](https://docs.pipecorn.com/api-reference/endpoints/signals/hiring.md) and
  [tech-stack search](https://docs.pipecorn.com/api-reference/endpoints/signals/tech_stack.md) (**3 credits**
  per imported company)

When the balance is too low the request is rejected up front with `402` and
nothing is spent, enqueued, or imported. Top up and replay the same request.

Credits belong to the workspace, so every member and every API key spends
from the same pool.

## Plan limits

Limits are quotas, not a balance. They come with your plan, reset on a fixed
schedule, and cannot be bought one at a time. There are two of them:

* **Profile scraping** (daily): how many people profiles you can extract per
  day. Drawn on by lead extraction, such as
  [search leads by filters](https://docs.pipecorn.com/api-reference/endpoints/leads/advanced_search.md),
  [extract leads from a Sales Navigator URL](https://docs.pipecorn.com/api-reference/endpoints/extract/leads.md),
  [leads in a company](https://docs.pipecorn.com/api-reference/endpoints/extract/leads_from_company.md), and
  [post engagers](https://docs.pipecorn.com/api-reference/endpoints/signals/post_engagers.md).
* **Company import** (daily and monthly): how many companies you can import
  per day and per month. Drawn on by account extraction, such as
  [search accounts by filters](https://docs.pipecorn.com/api-reference/endpoints/accounts/search.md),
  [extract accounts from a Sales Navigator URL](https://docs.pipecorn.com/api-reference/endpoints/extract/accounts.md),
  [lookalike companies](https://docs.pipecorn.com/api-reference/endpoints/signals/company_lookalike.md), and
  [growth signals](https://docs.pipecorn.com/api-reference/endpoints/signals/growth.md).

When a quota is used up the endpoint answers `422` with
`"Can't proceed with the request. Plan limit reached."`. Wait for the reset
or move to a plan with a higher allowance. Buying credits does nothing here.

### Scale: requests wait for the reset

On the Scale plan, a request your remaining quota cannot cover is queued
instead of refused. [Search accounts by filters](https://docs.pipecorn.com/api-reference/endpoints/accounts/search.md),
[extract accounts from a Sales Navigator URL](https://docs.pipecorn.com/api-reference/endpoints/extract/accounts.md),
[lookalike companies](https://docs.pipecorn.com/api-reference/endpoints/signals/company_lookalike.md),
[growth signals](https://docs.pipecorn.com/api-reference/endpoints/signals/growth.md) and
[post engagers](https://docs.pipecorn.com/api-reference/endpoints/signals/post_engagers.md) then answer
`202 Accepted` instead of `422`. The body is the usual `201` body plus two
fields:

```json theme={null}
{
  "status": "queued",
  "notice": "Plan limit reached. The request is queued and starts automatically once your quota resets.",
  "status_url": "https://app.pipecorn.com/api/v2/lists/8e1dcba0-f0bb-4071-99fc-f18ba6559ccc"
}
```

The import or search waits as `NOT_STARTED` at its `status_url` (also in the
`Location` header). It starts once the quota resets, then delivers to your
`webhook_url` as usual. Queued requests run one at a time, as the quota frees
up. Do not resend a queued request: each resend queues another copy.

A request larger than a whole day's quota still answers `422`, because no
reset could ever start it. Lower its `limit` and send it again.

> [!WARNING]
>
> In `GET /credits` the remaining quotas live under the `credits` key, next to
> `credits.enrichment`, and the field descriptions call them "credits". Read
> them as **remaining quota for the current period**, not as a spendable
> balance. Only `credits.enrichment` is money you can top up. The `limits`
> object gives each quota's ceiling so you can compute how much of the period
> you have used.

```json theme={null}
{
  "credits": {
    "enrichment": 3000,
    "daily_profile_scraping": 1500,
    "monthly_profile_scraping": 40000,
    "daily_company_import": 1000,
    "monthly_company_import": 10000
  },
  "limits": {
    "daily_profile_scraping": 2500,
    "monthly_profile_scraping": 50000,
    "daily_company_import": 1000,
    "monthly_company_import": 10000
  }
}
```

In this example the workspace has 3,000 enrichment credits to spend, and can
still extract 1,500 of its 2,500 daily profiles.

## Two other "limits" that are not plan limits

### Workspace weekly credit limit

A workspace admin can cap how many **enrichment credits** each member may
spend per week. This is a spending ceiling on credits, not a quota on
extraction. Hitting it returns `403 Forbidden` with
`code: "workspace_limit_exceeded"` and no `top_up_url`: the balance may be
fine, so buying credits does not help. An admin raises the member's weekly
allowance, or the limit resets at the end of the week.

### Rate limits

A per-minute request limit set by your plan, plus stricter caps on a few
endpoints, counted per user (not per API key). Credit-spending endpoints are exempt.
Exceeding one returns `429 Too Many Requests`. Rate limits are about request
pacing and have nothing to do with credits or quotas; back off and retry.

## Which one am I hitting?

Branch on the status code and, for `403`, on the `code` field.

| Response | What ran out | What unblocks it |
| - | - | - |
| `402` with `code: "insufficient_credits"` | Enrichment credit balance | Top up at `top_up_url`, or wait for plan renewal, then retry |
| `403` with `code: "workspace_limit_exceeded"` | Weekly credit spending cap for this member | Workspace admin raises the allowance, or the week resets |
| `403` with any other body | Nothing ran out: the account is closed, LinkedIn refused access to the resource, or your plan does not include the endpoint | See the `error` text in [403 Forbidden](https://docs.pipecorn.com/api-reference/errors.md); credits do not help |
| `422` with `"Plan limit reached."` | Daily profile scraping or daily/monthly company import quota | Wait for the reset, or upgrade the plan |
| `202` with `status: "queued"` | The same quota, on the Scale plan | Nothing: the request starts on its own once the quota resets |
| `429` | Request rate for this endpoint | Back off and retry |

For the exact response bodies and the list of endpoints that return each code,
see [Credit and limit errors](https://docs.pipecorn.com/api-reference/errors.md).

> [!NOTE]
>
> **History.** Until August 2026, enrich account and enrich people drew on the
> company import and profile scraping quotas and failed with `422` when they
> ran out. They are now priced in credits and answer `402` and `403` instead.
> See the [changelog](https://docs.pipecorn.com/changelog.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.