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

# Plans, quotas and capacity

> How an organization's plan decides which API calls succeed: license status, plan features, metered allowances, capacity slots and the API Calls allowance.

Your organization's plan decides what the API lets you do. A call can be refused by four checks, always in this order. Not every endpoint runs all four: [Plan features](#plan-features) lists which calls check a feature, and which need only a license in force or only a valid key. Each refusal has its own body, with one exception explained under [License in force](#license-in-force).

Each guide names its plan feature in an **Availability** line and what a call uses in a **Cost** line. This page explains both. There are no credits and no per-endpoint daily limits.

### The four checks

Your API key is checked first. A missing, revoked or expired key returns `401` before any of these checks run (see [Authentication](https://wiki.darknetsearch.com/api/guides/authentication.md)).

| Order | Check | Refusal | What to do |
| - | - | - | - |
| 1 | [License in force](#license-in-force) | `403` `{"detail": "Your license is not active."}` | Renew the plan. Retries fail until then. |
| 2 | [Plan feature](#plan-features) | `403` `{"detail": "This feature is not included in your plan."}` | Use a feature your plan includes, or change the plan. |
| 3 | Rate limit and [API Calls allowance](#api-calls-allowance) | `429` `{"message": "Rate limit exceeded", ...}` | Wait `retry_after_seconds`. See [Rate limits](https://wiki.darknetsearch.com/api/guides/rate-limits.md). |
| 4 | [Metered allowance](#metered-allowances) or [capacity slot](#capacity-slots) | `429` with `resource`, `period` and `limit`, or `409` with `resource` and `limit` | Wait for the next window or add a pack. Free a slot. |

A call refused at check 1 or 2 never reaches the rate limiter, so it uses none of your API Calls allowance. A call refused at check 4 returns a non-`2xx` status, so its API call is refunded.

Every error body is listed once in [Handle API errors](https://wiki.darknetsearch.com/api/guides/errors.md).

### License in force

A license is in force when its status is one of these:

| Status | Meaning |
| - | - |
| `active` | The plan is within its term. |
| `grace` | The term has ended. The plan keeps working for 30 days after the end date. |
| `pending` | A new plan is ordered and its invoice is not yet paid. The plan works while the invoice is open. |

A suspended or expired license is not in force. Status changes run once a day. A demo license has no grace period: it works through its end date and stops the next day.

A client workspace needs two licenses in force: its own and the license of the organization that manages it. When the managing organization's license lapses, every client workspace it manages is refused too. See [Client workspaces](#client-workspaces).

Without a license in force, most calls return `403`:

```json theme={"dark"}
{
  "detail": "Your license is not active."
}
```

Match the start of `detail`, not the whole string.

> [!WARNING]
>
> **A lapsed license can look like a missing feature.** On an endpoint that needs a plan feature, a lapsed license returns `"This feature is not included in your plan."` instead. If a call that used to work starts returning that message, check your license status first.

[`get_direct_org_info`](https://client-api.leak.center/scalar-docs/#tag/organization-settings/GET/api/service/get_direct_org_info/) still answers without a license in force, so you can confirm which organization a key acts as.

### Plan features

A plan feature unlocks a group of endpoints. Without the feature, the endpoints that check it return `403`:

```json theme={"dark"}
{
  "detail": "This feature is not included in your plan."
}
```

Some features are checked on every endpoint. Others are checked only on the call that starts a search or changes a setting, and reading the results needs less. The **Checked on** column says which. Most feature names match the plan in the dashboard, under **Manage** → **Buy more**. See [Where to see your plan and usage](#where-to-see-your-plan-and-usage).

| Guide | Plan feature | Checked on | What a call uses |
| - | - | - | - |
| [Telegram](https://wiki.darknetsearch.com/api/guides/expert-telegram.md) and [Discord](https://wiki.darknetsearch.com/api/guides/expert-discord.md) searches | Telegram/Discord Monitoring | Every endpoint | No allowance |
| [Pastes](https://wiki.darknetsearch.com/api/guides/expert-pastes.md) | Paste Leaks | Every endpoint | No allowance |
| [Credit cards](https://wiki.darknetsearch.com/api/guides/expert-credit-cards.md) | Credit Card Exposure | `cc_leaks_search` | No allowance |
| [Open cloud storage](https://wiki.darknetsearch.com/api/guides/expert-cloud-storage.md) | Cloud Storage Exposure | Search requests, not their results | No allowance |
| [URL shorteners](https://wiki.darknetsearch.com/api/guides/expert-url-shorteners.md) | URL Shortener Abuse | Search requests, not their results | No allowance |
| [App stores](https://wiki.darknetsearch.com/api/guides/expert-app-store.md) | App Store Impersonation | Search requests, not their results | No allowance |
| [Threat actor publications](https://wiki.darknetsearch.com/api/guides/expert-threat-actors.md) | Ransomware Threat Actor Monitoring | Every endpoint | No allowance |
| [Monitors](https://wiki.darknetsearch.com/api/guides/monitoring-rules.md#data-sources) on the legacy Hacker Forum DB source (`8`) | Hacker Forum Access | Creating and updating such a monitor | No allowance |
| [Tor & I2P Network](https://wiki.darknetsearch.com/api/guides/live-search#tor-&-i2p-network) | Onion Search | `external_sources_search` | No allowance |
| [Email References](https://wiki.darknetsearch.com/api/guides/live-search#email-references) | Email Exposure (Surface Web) | `mails_external_search` | No allowance |
| [Live Data Broker Search](https://wiki.darknetsearch.com/api/guides/live-data-brokers.md) | Live Data Broker | Every endpoint except the two purchase endpoints | 1 unit per search |
| [Infra search](https://wiki.darknetsearch.com/api/guides/infra-search.md) | Attack Surface Mapping | Search requests, not their results or `infra_search_stats` | 1 unit per scan |
| [Attack Surface assessments](https://wiki.darknetsearch.com/api/guides/attack-surface-assessments.md) | Attack Surface Reports (full) or Targeted Attack Surface Reports (targeted). Either one opens the assessment lists, reports, templates and exclusions. | Every endpoint | 1 unit per assessment |
| [Credential comparison reports](https://wiki.darknetsearch.com/api/guides/reports-credential-comparison.md) | Credential Report | `generate_credential_comparison_report` | 1 unit per report |
| [Code exposure](https://wiki.darknetsearch.com/api/guides/code-exposure.md) | Exposed Code Detection | Every endpoint | 1 unit per unique keyword, 1 per contributor scan |
| [Domain monitoring](https://wiki.darknetsearch.com/api/guides/domain-monitoring.md) | Domain Monitoring, listed as SpoofGuard on your plan | Every endpoint | 1 Monitored Assets slot per domain |
| [Domain takedowns](https://wiki.darknetsearch.com/api/guides/domain-takedowns.md) | Domain takedowns, which come with SpoofGuard on your plan | Every takedown and power of attorney endpoint | 1 unit per takedown sent |
| Webhooks in [delivery settings](https://wiki.darknetsearch.com/api/guides/monitoring-delivery.md) | Webhooks | Every webhook endpoint | No allowance |
| Custom senders and email templates in [delivery settings](https://wiki.darknetsearch.com/api/guides/monitoring-delivery.md) | Custom Email Server | Creating, updating and deleting senders and templates | No allowance |

Report schedules for the [credential comparison report](https://wiki.darknetsearch.com/api/guides/reports-credential-comparison.md#schedule-a-monthly-report) check a separate report feature that every plan includes. You meet its `403` only when your license is not in force.

#### Which plans include each feature

The standard plans include these features. **Manage** → **Buy more** in the dashboard shows what your own plan includes.

| Plan feature | Starter | Advanced | Pro | MSSP Small and MSSP Large |
| - | - | - | - | - |
| Telegram/Discord Monitoring | No | Yes | Yes | Yes |
| Paste Leaks | No | No | Yes | Yes |
| Credit Card Exposure | No | No | Yes | Yes |
| Cloud Storage Exposure | No | No | Yes | Yes |
| URL Shortener Abuse | No | No | Yes | Yes |
| App Store Impersonation | No | No | Yes | Yes |
| Ransomware Threat Actor Monitoring | No | Yes | Yes | Yes |
| Hacker Forum Access | No | Yes | Yes | Yes |
| Onion Search | No | No | Yes | Yes |
| Email Exposure (Surface Web) | No | Yes | Yes | Yes |
| Live Data Broker | No | Yes | Yes | Yes |
| Attack Surface Mapping | Yes | Yes | Yes | Yes |
| Attack Surface Reports and Targeted Attack Surface Reports | Yes | Yes | Yes | Yes |
| Credential Report | Yes | Yes | Yes | Yes |
| Exposed Code Detection | No | No | Yes | Yes |
| Domain Monitoring | No | Yes | Yes | Yes |
| Domain takedowns | No | Yes | Yes | Yes |
| Webhooks | No | No | Yes | Yes |
| Custom Email Server | No | No | Yes | Yes |
| API Calls | No | Medium and Large organizations | Yes | Yes |

API keys need an API Calls allowance. See [Authentication](https://wiki.darknetsearch.com/api/guides/authentication.md).

#### What needs only a license in force

These endpoints check no plan feature. A license in force is enough:

* [Quick search](https://wiki.darknetsearch.com/api/guides/wide-search.md). Each source still needs its own feature. A source your plan excludes comes back with `"status": "not_entitled"`, and the other sources still run.
* Leaked credentials: [Raw Data](https://wiki.darknetsearch.com/api/guides/credentials-raw-sweep.md), [Filtered credentials](https://wiki.darknetsearch.com/api/guides/credentials-filtered.md), the [ULP feed](https://wiki.darknetsearch.com/api/guides/credentials-ulp-feed.md), [stealer logs](https://wiki.darknetsearch.com/api/guides/credentials-stealer-logs.md), [Credential Check](https://wiki.darknetsearch.com/api/guides/credentials-check.md) and [credential exposure analytics](https://wiki.darknetsearch.com/api/guides/credentials-org-analytics.md).
* [SSL Transparency Logs](https://wiki.darknetsearch.com/api/guides/expert-ssl-logs.md), [new domain registrations](https://wiki.darknetsearch.com/api/guides/expert-domain-registrations.md) and [Data Brokers listings](https://wiki.darknetsearch.com/api/guides/expert-data-brokers.md).
* [Risk score](https://wiki.darknetsearch.com/api/guides/risk-score.md).
* [Monitor](https://wiki.darknetsearch.com/api/guides/monitoring-rules.md) matches, exclusions and metrics, and email delivery to recipients.
* The export service and leak-file downloads in [Downloads and exports](https://wiki.darknetsearch.com/api/guides/downloads-exports.md). A source's own file endpoint follows its source. For example, the Code exposure export needs Exposed Code Detection, and the Attack Surface report download needs an Attack Surface feature.
* Every other endpoint of Credit cards, Tor & I2P and Email References, such as results, status, details and deletes. Only the search call checks the feature.
* Reading custom senders and email templates.
* The two [Live Data Broker](https://wiki.darknetsearch.com/api/guides/live-data-brokers.md) purchase endpoints.

#### What needs only a valid API key

These endpoints check neither a license nor a plan feature. They answer whenever your API key is valid:

* Every [phishing references](https://wiki.darknetsearch.com/api/guides/expert-phishing.md) endpoint.
* The results of Open cloud storage, URL shortener, App store and Infra search requests, and `infra_search_stats`.
* Listing [credential comparison reports](https://wiki.darknetsearch.com/api/guides/reports-credential-comparison.md), checking their status, downloading them and deleting them.
* `get_direct_org_info`.

#### Monitors and their data sources

Creating or updating a [monitor](https://wiki.darknetsearch.com/api/guides/monitoring-rules.md) checks the plan feature of its data source:

| Monitor data source | Plan feature |
| - | - |
| Credit cards, BIN and CVV | Credit Card Exposure |
| Pastes | Paste Leaks |
| Ransomware | Ransomware Threat Actor Monitoring |
| Hacker forums | Hacker Forum Access |
| Open cloud storage | Cloud Storage Exposure |
| URL shorteners | URL Shortener Abuse |
| App stores | App Store Impersonation |
| Telegram, Discord | Telegram/Discord Monitoring |

Every other data source needs only a license in force.

### Metered allowances

Some features come with an allowance: a number of units per window. The call that starts the work takes its units before it runs.

| Allowance | `resource` | Used by | Units | Window |
| - | - | - | - | - |
| Attack Surface Mapping | `infra_search_scan` | Starting an [infra search](https://wiki.darknetsearch.com/api/guides/infra-search.md) scan | 1 per scan | Month |
| Attack Surface Reports | `attack_surface_report` | Starting a full [assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-assessments.md) | 1 per assessment | Month |
| Targeted Attack Surface Reports | `targeted_attack_surface_report` | Starting a targeted [assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-assessments.md) | 1 per assessment | Month |
| Credential Report | `credential_report` | Generating a [credential comparison report](https://wiki.darknetsearch.com/api/guides/reports-credential-comparison.md) | 1 per report | Month |
| Live Data Broker | `hacker_forum_live_search` | Starting a [Live Data Broker search](https://wiki.darknetsearch.com/api/guides/live-data-brokers.md) | 1 per search | Month |
| Code Exposure Keywords | `code_exposure_keyword_search` | Starting [keyword scans](https://wiki.darknetsearch.com/api/guides/code-exposure.md) | 1 per unique keyword | Month |
| Code Exposure Contributors | `code_exposure_contributor_search` | Starting a [contributor scan](https://wiki.darknetsearch.com/api/guides/code-exposure.md) | 1 per scan | Month |
| Domain takedowns | `domain_take_down` | Sending a [takedown](https://wiki.darknetsearch.com/api/guides/domain-takedowns.md) | 1 per takedown | Year |

Every other plan feature has no allowance. Its calls are limited only by the [rate limit](https://wiki.darknetsearch.com/api/guides/rate-limits.md) and, with an API key, the [API Calls allowance](#api-calls-allowance).

#### How units are counted

* **Taken before the call runs.** Reads, polling, results, lists and deletes use no units.
* **Refunded on any non-`2xx` response.** A `2xx` response keeps its units, even if the job it started fails later or you delete it.
* **All or nothing.** A call that needs more units than remain is refused whole. No units are taken.
* **Counted per unique keyword for Code exposure.** Keywords are compared case-insensitively across every source in one request. The request below uses 2 units: `acme.com` and `ACME.com` count once.

```bash theme={"dark"}
curl https://client-api.leak.center/api/code_scan/keyword_scans/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      {"source": "github", "keywords": [{"keyword": "acme.com"}, {"keyword": "acme-login.com"}]},
      {"source": "postman", "keywords": [{"keyword": "ACME.com"}]}
    ]
  }'
```

#### Windows

A monthly allowance resets on the 1st of each month at 00:00 UTC. The Domain takedowns allowance is yearly and runs per contract year: it resets at 00:00 UTC on each anniversary of your license's start date. Unused units do not carry over.

#### Packs

A pack adds units to an allowance, or slots to a capacity, once it is paid. A monthly pack adds its units to every monthly window, and a yearly takedown pack adds its takedowns to the contract year. **Manage** → **Buy more** in the dashboard lists the packs your plan can add.

#### When an allowance is spent

The call returns `429` and does not run:

```json theme={"dark"}
{
  "detail": "You have reached your Code Exposure Keyword Search limit for this month.",
  "resource": "code_exposure_keyword_search",
  "period": "month",
  "limit": 10
}
```

* `resource` is the allowance from the table above. Branch on it, not on `detail`.
* `period` is the window that ran out. It is `month` for every allowance except Domain takedowns, which use `year`. Read it from the body rather than assume it.
* `limit` is your organization's units for the window, packs included.

This `429` has no `Retry-After` header. Retrying fails until the window resets or a pack is added. A `429` with `"message": "Rate limit exceeded"` is a different refusal: see [API Calls allowance](#api-calls-allowance).

### Capacity slots

Some things you keep, rather than run, hold a slot for as long as they exist. Slots never reset. You free one by removing what holds it.

| Slot | `resource` | Held by | Taken by | Freed by |
| - | - | - | - | - |
| Monitored Assets | `monitored_assets` | Each [monitor](https://wiki.darknetsearch.com/api/guides/monitoring-rules.md), and each distinct domain with at least one [domain scan](https://wiki.darknetsearch.com/api/guides/domain-monitoring-scans.md) | Creating a monitor, or starting a scan | Deleting the monitor, or the domain's last scan |
| Scheduled reports | `automated_reports` | Each active [credential comparison report](https://wiki.darknetsearch.com/api/guides/reports-credential-comparison.md) schedule | Creating a schedule with `is_active` set to `true` (the default), or setting it to `true` later | Setting `is_active` to `false` |

When every slot is in use, the call that would take one more returns `409`:

```json theme={"dark"}
{
  "detail": "You have reached your Monitored Assets limit of 25.",
  "resource": "monitored_assets",
  "limit": 25
}
```

`limit` is your organization's slot count, packs included. Nothing is created. Free a slot or add a pack, then send the call again.

* **Monitors.** One monitor holds one slot until you delete it.
* **Domain monitoring.** Each scanned domain holds a slot from the same Monitored Assets pool as your monitors. At the limit, `start_domain_analysis` returns `409` for any domain, including one you already scan. To scan a monitored domain again, use `analysis_rescan`, which needs no free slot.
* **Report schedules.** Only active schedules hold a slot. A plan can include zero schedule slots, and then every active schedule is refused. A schedule created with `is_active` set to `false` holds no slot. To pause or resume a schedule, `update_report_schedule` needs the schedule's `domains` and `mask_passwords` in the body as well as `is_active`, for example `{"domains": ["acme.com"], "is_active": false, "mask_passwords": true}`. See [Change, pause or resume a schedule](https://wiki.darknetsearch.com/api/guides/reports-credential-comparison.md#change-pause-or-resume-a-schedule).

Admin seats and client workspaces are slots too. You manage them in the dashboard. Registered assets hold no slot.

### API Calls allowance

Every request made with an API key counts toward your organization's monthly **API Calls** allowance. Only `2xx` responses count: every other response is refunded. You can create API keys only when your plan includes API Calls (see [Authentication](https://wiki.darknetsearch.com/api/guides/authentication.md)). A separate per-second rate limit applies to every caller and is counted per organization.

When either limit is hit, the call returns `429` with `"message": "Rate limit exceeded"`, a `Retry-After` header and `retry_after_seconds`. The `X-RateLimit-*` headers describe these two limits only, never a feature allowance or a slot. [Rate limits](https://wiki.darknetsearch.com/api/guides/rate-limits.md) explains both limits, the headers and how to pace a batch job.

### Where to see your plan and usage

In the [dashboard](https://dashboard.darknetsearch.com), both pages show the workspace you are in. With client workspaces, pick one in the workspace switcher at the top of the sidebar.

* **Manage** → **Usage** shows what is used and left of each allowance and slot, and when each one resets. Org Admins, System Admins and System Users can open it.
* **Manage** → **Buy more** shows the features your plan includes and the packs it can add. Org Admins and System Admins can buy packs and change the plan there.

From the API:

* `limit` in every `429` allowance body and every `409` capacity body gives your current total.
* [`get_api_call_usage`](https://client-api.leak.center/scalar-docs/#tag/general-endpoints/GET/api/service/get_api_call_usage/) returns every request your organization made, from the dashboard and with API keys, per month and per day, broken down by status code. It is a traffic log, not your API Calls allowance balance.

### Client workspaces

Most partners serve every client from their own organization, which the dashboard calls a workspace. They register each client's domains and other assets in it and use one API key. Every check then uses your own license, plan features, allowances, slots and limits.

A client workspace is a separate organization, bought for a client that signs in to the dashboard itself. It has its own plan. A key created for a client workspace acts as that workspace, so every check uses its own license, plan features, allowances, slots, API Calls allowance and per-second rate limit. Its calls also need the managing organization's license in force.

See [Client organizations](https://wiki.darknetsearch.com/api/guides/authentication.md#client-organizations) for the keys. System Admins and System Users see every client workspace under **Manage** → **Workspaces**.

### Endpoints

| Action | Uses | Endpoint |
| - | - | - |
| Start an infra search scan | Attack Surface Mapping, 1 unit | [`POST /api/service/create_infra_search_request/`](https://client-api.leak.center/scalar-docs/#tag/infra-search/POST/api/service/create_infra_search_request/) |
| Start a full assessment | Attack Surface Reports, 1 unit | [`POST /api/hackerview/scans/full/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/scans/full/) |
| Start a targeted assessment | Targeted Attack Surface Reports, 1 unit | [`POST /api/hackerview/scans/targeted/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/scans/targeted/) |
| Generate a credential comparison report | Credential Report, 1 unit | [`POST /api/service/generate_credential_comparison_report/`](https://client-api.leak.center/scalar-docs/#tag/report/POST/api/service/generate_credential_comparison_report/) |
| Start a Live Data Broker search | Live Data Broker, 1 unit | [`POST /api/service/live_search_create/`](https://client-api.leak.center/scalar-docs/#tag/live-search/POST/api/service/live_search_create/) |
| Start keyword scans | Code Exposure Keywords, 1 unit per unique keyword | [`POST /api/code_scan/keyword_scans/`](https://client-api.leak.center/scalar-docs/#tag/code-scan/POST/api/code_scan/keyword_scans/) |
| Start a contributor scan | Code Exposure Contributors, 1 unit | [`POST /api/code_scan/contributor_scans/`](https://client-api.leak.center/scalar-docs/#tag/code-scan/POST/api/code_scan/contributor_scans/) |
| Send a takedown | Domain takedowns, 1 unit | [`POST /api/spoofguard/takedowns/{takedown_id}/send/`](https://client-api.leak.center/scalar-docs/#tag/spoofguard/POST/api/spoofguard/takedowns/\{takedown_id}/send/) |
| Create a monitor | 1 Monitored Assets slot | [`POST /api/service/alert_system_alert_create_alert_rule/`](https://client-api.leak.center/scalar-docs/#tag/alert-system/POST/api/service/alert_system_alert_create_alert_rule/) |
| Delete a monitor | Frees its slot | [`DELETE /api/service/alert_system_alert_delete_alert_rule/{id}/`](https://client-api.leak.center/scalar-docs/#tag/alert-system/DELETE/api/service/alert_system_alert_delete_alert_rule/\{id}/) |
| Start a domain scan | 1 Monitored Assets slot per new domain | [`POST /api/service/start_domain_analysis/`](https://client-api.leak.center/scalar-docs/#tag/spoofguard/POST/api/service/start_domain_analysis/) |
| Scan a monitored domain again | No slot | [`POST /api/service/analysis_rescan/{analysis_id}/`](https://client-api.leak.center/scalar-docs/#tag/spoofguard/POST/api/service/analysis_rescan/\{analysis_id}/) |
| Delete a domain scan | Frees the domain's slot when no scan of it remains | [`DELETE /api/service/analysis_delete/{analysis_id}/`](https://client-api.leak.center/scalar-docs/#tag/spoofguard/DELETE/api/service/analysis_delete/\{analysis_id}/) |
| Create a report schedule | 1 Scheduled reports slot when active | [`POST /api/service/create_report_schedule/`](https://client-api.leak.center/scalar-docs/#tag/report/POST/api/service/create_report_schedule/) |
| Activate or deactivate a report schedule | Takes or frees a slot. Send `domains` and `mask_passwords` too. | [`PATCH /api/service/update_report_schedule/{schedule_id}/`](https://client-api.leak.center/scalar-docs/#tag/report/PATCH/api/service/update_report_schedule/\{schedule_id}/) |
| Check which organization a key acts as | Works without a license in force | [`GET /api/service/get_direct_org_info/`](https://client-api.leak.center/scalar-docs/#tag/organization-settings/GET/api/service/get_direct_org_info/) |
| Read your organization's request log | — | [`GET /api/service/get_api_call_usage/`](https://client-api.leak.center/scalar-docs/#tag/general-endpoints/GET/api/service/get_api_call_usage/) |


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