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

# Usage metadata and retries

> Understand what counts as a profile and how to retry safely.

## What uses a profile?

| Request                                             | Profiles used                |
| --------------------------------------------------- | ---------------------------- |
| Company or people search                            | 0; active allowance required |
| Successful new company or person lookup             | 1                            |
| Eligible repeat of the same profile within 24 hours | 0                            |
| Eligible replay with the same idempotency key       | 0 additional                 |
| Authentication check or MCP tool discovery          | 0                            |

Company and person profiles count equally. REST and MCP share your account's
allowance. Work email, when requested, is included in the person lookup; a valid
person profile still counts if an email is absent, invalid or uncertain.

No match, invalid input and provider failures do not create a new profile debit.
However, a network failure after a lookup has committed can leave a completed
deduction. Always preserve the idempotency key for retries.

## Repeat window

The 24-hour window starts at the supporting lookup that used one profile. Repeats
do not restart that clock. Eligibility is scoped to your account and the same
resolved company or person identity, across REST and MCP. An active allowance is
still required. Reversed funding cannot support included repeats or replays.

## Idempotency

For REST lookups, send `Idempotency-Key` with a unique identifier containing 1–128
letters, numbers, underscores or hyphens. Reuse it only for retries of the same
operation and normalized input within the eligible window.

Changing the input, resolving to a different profile or replaying after the
eligible window returns `409`. Start a new logical lookup with a new key in those
cases. A replay can refetch current data; it is not a cached response. It does not
extend the supporting paid lookup's repeat window.

The hosted MCP server forwards a valid `Idempotency-Key` HTTP header when supplied
by the client, otherwise it generates one. It is not an additional tool argument.

## Read the response metadata

| `meta.billing_status` | Meaning                                           |
| --------------------- | ------------------------------------------------- |
| `search_included`     | Search completed without a profile deduction.     |
| `profile_deducted`    | One new profile was deducted.                     |
| `repeat_included`     | This profile was eligible for an included repeat. |
| `idempotent_replay`   | This eligible request was already settled.        |

`meta.profiles_used` reports the deduction caused by this request: `0` or `1`.
`meta.request_id` identifies the request. Retain it when reporting an issue.

## Request limits

Data operations share a limit of 60 requests per fixed minute per account. Searches,
lookups and replays count toward that limit. The data provider can also rate-limit
requests. On `429`, wait before retrying; see [errors](/errors).

Search pages default to 10 results and support `limit` from 1 to 25 and `offset`
from 0 to 1,000. Request bodies are limited to 16 KiB. People search can be slow or
time out; use focused filters and avoid rapid repeated retries.

## Planned paid plan

Paid checkout is not enabled during the current private preview. The planned plan
is USD 25/month for 1,000 profiles, with an additional USD 25 for 1,000 profiles
within the current paid period. Unused profiles do not roll over, and top-ups
expire at renewal. This describes the planned offering, not an available checkout.