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

# Credits & Usage

> How API credits are counted and how to retrieve your team's current usage.

API credits are consumed based on **results returned, not requests made**. You're charged for what you actually receive — failed calls and empty responses cost 0 credits.

## What costs credits

| Endpoint                                                                                                                                   | Cost                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [Search Profiles](/docs/endpoints/v3/search-profiles), [Search Companies](/docs/endpoints/v3/search-companies)                             | Free                                                                     |
| [Fetch Profile](/docs/endpoints/v3/fetch-profile), [Fetch Company](/docs/endpoints/v3/fetch-company)                                       | **1 credit per record returned**                                         |
| [Relationships](/docs/endpoints/v3/relationships)                                                                                          | Free                                                                     |
| [Network Mapper](/docs/endpoints/v3/network-mapper) (for Partners)                                                                         | **1 credit per non-empty response**                                      |
| [Refresh a Profile](/docs/on-demand/refresh-profile)                                                                                       | **3 credits per profile returned**                                       |
| [Get Profile Posts](/docs/on-demand/get-profile-posts), [Get Company Posts](/docs/on-demand/get-company-posts)                             | **1 credit per 10 posts returned** (rounded up, max 10 credits per call) |
| [Get Comments](/docs/on-demand/get-comments), [Get Reactions](/docs/on-demand/get-reactions), [Get Reshares](/docs/on-demand/get-reshares) | **1 credit per call** (flat, regardless of result count)                 |

## Examples

| Action                              | Credits |
| ----------------------------------- | ------- |
| Search returning 250 profiles       | 0       |
| Fetch 10 profiles, all returned     | 10      |
| Fetch 10 profiles, 0 returned       | 0       |
| Refresh 1 profile                   | 3       |
| Refresh 20 profiles                 | 60      |
| Get posts, 8 returned               | 1       |
| Get posts, 15 returned              | 2       |
| Get posts, 100 returned             | 10      |
| Get comments / reactions / reshares | 1       |
| Any failed request (non-200)        | 0       |

## Plans and overages

Each plan includes a monthly credit allowance that resets at the start of every billing cycle — credits don't roll over. Once the included credits are used, additional usage is billed at the plan's overage rate.

See [Plans, Billing & API Credits](https://help.theswarm.com/en/articles/14121950-plans-billing-connector-limits-api-credits) and [Understanding API credit overages](https://help.theswarm.com/en/articles/14125438-understanding-api-credit-overages).

## Overage protection

Overage protection lets you cap API spend at your plan's included credits. It applies to all paid plans (Premium and Enterprise) and is **off by default** — additional usage beyond your monthly allowance is billed at the plan's overage rate (see [pricing](https://www.theswarm.com/pricing)).

Toggle it from the [API settings in your dashboard](https://app.theswarm.com/api#overage-protection):

* **Off (default):** Requests continue to succeed after you exhaust your included credits. Any additional credits are billed as overages.
* **On:** Requests to endpoints that consume credits are paused as soon as your team reaches its monthly credit limit. No overage charges will occur. Access resumes automatically at the start of the next billing cycle.

When overage protection is on and the limit is reached, credit-consuming endpoints return a `402 Payment Required` response:

```json theme={null}
{
  "status": 402,
  "errors": [
    {
      "code": "OVERAGE_PROTECTION_ENABLED",
      "message": "Requests paused by Overage Protection. Turn it off to continue at overage rates, or upgrade your plan.",
      "resolution": {
        "enable_overages": "https://app.theswarm.com/api#overage-protection",
        "upgrade_plan": "https://app.theswarm.com/upgrade-plan"
      }
    }
  ]
}
```

To restore access before the next cycle, either turn overage protection off or [upgrade your plan](https://app.theswarm.com/upgrade-plan).

## Check your usage

Retrieve your team's credit usage for the current billing period.

```text theme={null}
GET https://bee.theswarm.com/credits/usage
```

Authenticate with your API key in the `x-api-key` header.

### Response

```json theme={null}
{
  "usage": 2255235
}
```

| Field   | Type    | Description                                     |
| :------ | :------ | :---------------------------------------------- |
| `usage` | integer | Credits consumed in the current billing period. |

### Example request

```bash theme={null}
curl -X GET "https://bee.theswarm.com/credits/usage" \
  -H "x-api-key: <your_api_key>"
```