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

# Per-Call Credit Usage

> Opt in to per-call credit reporting and receive the exact credits deducted for each API request directly in the response.

## Overview

The **Per-Call Credit Usage** feature lets you see exactly how many credits a request consumed, returned inline with that request's response. This gives you call-level visibility into consumption so you can track, attribute, and optimize your usage in real time, without making a separate call to the [Credits aggregation](https://developers.explorium.ai/v2/credits/credits_aggregation.md) endpoint.

The feature is **opt-in**. It is enabled per request via a request header and has **no effect** on existing integrations that don't send the header.

&#x20;**Why is this useful?**

* **Real-time cost attribution** — Know the cost of each call as it happens, without polling an aggregation endpoint.
* **Usage optimization** — Compare the credit cost of different filters and page sizes to tune your queries.
* **Accurate downstream reporting** — Tooling and integrations (such as MCP-based agents) can report precise resource usage back to the caller.

> [!NOTE]
>
> Enabling this feature does **not** consume additional credits. It only reports the credits already deducted for the request you made.

## Enabling Per-Call Credit Usage

Opt in by sending the following request header:

```bash theme={null}
credit-usage: true
```

When this header is present and set to `true`, the response includes an additional `credit_usage` object alongside the standard payload. When the header is **omitted** or set to **any other value**, the response is returned unchanged.

## Request Header

**credit-usage** `boolean` (default: false)

Set to `true` to include the `credit_usage` object in the response.

Any other value, or omitting the header entirely, leaves the response unchanged. The header is case-insensitive in its value (`true` / `True`).

## Response

When opted in, the standard response payload is returned with one additional top-level field:

**credit\_usage** `object`

Credit consumption details for this specific API call. Present only when the request includes `credit-usage: true`.

**properties**

**total\_results** `integer`

The number of results included in this specific response (i.e. the records actually returned by this call).

**total\_credits** `integer`

The number of credits deducted for this specific API call.

> [!NOTE]
>
> `credit_usage.total_results` reports the number of records **returned and billed in this call**, which is not the same as the top-level `total_results` field that some endpoints return. The top-level `total_results` reflects the **total number of records that match your filters** across all pages, while `credit_usage.total_results` reflects only what this single response returned.

## Examples

### Request

```bash Fetch Businesses theme={null}
curl --request POST \
  --url https://api.explorium.ai/v2/businesses \
  --header 'Content-Type: application/json' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'credit-usage: true' \
  --data '{
    "mode": "full",
    "page_size": 100,
    "filters": {
      "country_code": {
        "values": ["us"]
      },
      "company_size": {
        "values": ["11-50", "51-200"]
      }
    }
  }'
```

```python Python theme={null}
import requests

url = "https://api.explorium.ai/v2/businesses"
headers = {
    "Content-Type": "application/json",
    "api_key": "YOUR_API_KEY",
    "credit-usage": "true",
}
payload = {
    "mode": "full",
    "page_size": 100,
    "filters": {
        "country_code": {"values": ["us"]},
        "company_size": {"values": ["11-50", "51-200"]},
    },
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(data["credit_usage"]["total_credits"])
```

```javascript Node.js theme={null}
const response = await fetch("https://api.explorium.ai/v2/businesses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api_key": "YOUR_API_KEY",
    "credit-usage": "true",
  },
  body: JSON.stringify({
    mode: "full",
    page_size: 100,
    filters: {
      country_code: { values: ["us"] },
      company_size: { values: ["11-50", "51-200"] },
    },
  }),
});

const data = await response.json();
console.log(data.credit_usage.total_credits);
```

### Response

```json Opted In (credit-usage: true) theme={null}
{
  "response_context": {
    "correlation_id": "9d7864f9ee2b450bbf84e2f4a2d81292",
    "request_status": "success",
    "time_taken_in_seconds": 0.42
  },
  "data": [
    {
      "business_id": "8adce3ca1cef0c986b22310e369a0793",
      "name": "Acme Corporation",
      "domain": "acme.com"
    }
  ],
  "total_results": 4321,
  "page": {
    "size": 100,
    "next_cursor": "0.0|2571821.0|8adce3ca1cef0c986b22310e369a0793"
  },
  "credit_usage": {
    "total_credits": 100,
    "total_results": 100
  }
}
```

```json Opted Out (header omitted) theme={null}
{
  "response_context": {
    "correlation_id": "9d7864f9ee2b450bbf84e2f4a2d81292",
    "request_status": "success",
    "time_taken_in_seconds": 0.42
  },
  "data": [
    {
      "business_id": "8adce3ca1cef0c986b22310e369a0793",
      "name": "Acme Corporation",
      "domain": "acme.com"
    }
  ],
  "total_results": 4321,
  "page": {
    "size": 100,
    "next_cursor": "0.0|2571821.0|8adce3ca1cef0c986b22310e369a0793"
  }
}
```

## Behavior

| Header value | Response behavior |
| :- | :- |
| `credit-usage: true` | Standard payload **plus** the `credit_usage` object. |
| Any other value | Standard payload, unchanged. No `credit_usage` object. |
| Header omitted | Standard payload, unchanged. No `credit_usage` object. |

Because the field is only added when you explicitly opt in, existing integrations are unaffected and the change is fully backward compatible.

## Supported Endpoints

The `credit-usage` header is supported across the v2 endpoints, including:

* **Businesses** — Fetch Businesses, Match Businesses, Fetch Businesses Statistics, synchronous Business Enrichments (`.../enrich`), and Business Events.
* **Prospects** — Fetch Prospects, Match Prospects, Fetch Prospects Statistics, synchronous Prospect Enrichments (`.../enrich`), and Prospect Events.

Endpoints that don't charge credits, such as Match, still return the `credit_usage` object when you opt in, with `total_credits: 0`.

> [!NOTE]
>
> **Async jobs report credit usage automatically.** For enrichments submitted through `.../job`, you don't need the header: the [job status](https://developers.explorium.ai/v2/jobs/get_job_status.md) response includes a `credit_usage` object once the job finishes.

## Related

* [Get credits](https://developers.explorium.ai/v2/credits/get_credits.md) — Check your current credit balance.
* [Credits aggregation](https://developers.explorium.ai/v2/credits/credits_aggregation.md) — Retrieve aggregated consumption across time ranges or endpoints.
* [Tracking Your Credits](https://developers.explorium.ai/reference/credits/tracking_your_credits.md) — Monitor overall usage in the Admin Portal.

&#x20;Need help? Contact [support@explorium.ai](mailto:support@explorium.ai).
