Credits & 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, Search Companies	Free
Fetch Profile, Fetch Company	1 credit per record returned
Relationships	Free
Network Mapper (for Partners)	1 credit per non-empty response
Refresh a Profile	3 credits per profile returned
Get Profile Posts, Get Company Posts	1 credit per 10 posts returned (rounded up, max 10 credits per call)
Get Comments, Get Reactions, 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 and 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). Toggle it from the API settings in your dashboard:

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:

{
  "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.

Check your usage

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

GET https://bee.theswarm.com/credits/usage

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

Response

{
  "usage": 2255235
}

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

Example request

curl -X GET "https://bee.theswarm.com/credits/usage" \
  -H "x-api-key: <your_api_key>"

Using the API

Endpoints (v3)

Team Management

For Partners

On Demand

What costs credits

Examples

Plans and overages

Overage protection

Check your usage

Response

Example request

​What costs credits

​Examples

​Plans and overages

​Overage protection

​Check your usage

​Response

​Example request

What costs credits

Examples

Plans and overages

Overage protection

Check your usage

Response

Example request