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

# Pricing and caching

> How Topograph data blocks, documents, budgets, and deduplication work

Topograph prices are country-specific and can change as coverage evolves. Use [Coverage and pricing](/essentials/coverage-and-pricing) for the live human-readable catalog and `GET /v2/pricing` for application logic.

<Card title="Live pricing catalog" icon="arrow-up-right-from-square" href="https://topograph.co/pricing">
  View current country coverage, data block availability, document coverage, sources, and prices.
</Card>

## How billing works

Topograph bills by data block and document. A data block is the smallest billable unit for structured data in a country. A block can cover one or more datapoints, depending on how that country's sources are packaged.

Common datapoints include:

* `company`
* `legalRepresentatives`
* `otherKeyPersons`
* `establishments`
* `shareholders`
* `subsidiaries`
* `ultimateBeneficialOwners`
* `availableDocuments`
* `graph`

<Info>
  Search and request-result polling by `requestId` are not billed as new company data requests. `availableDocuments` lists document metadata; document downloads are billed only when you request specific document IDs.
</Info>

## 24-hour deduplication

When you request the same billable block for the same company within 24 hours, Topograph deduplicates the charge for your account. The later request links to the previous billing event rather than creating a duplicate charge.

This matters for multi-step flows: you can request `company` first, then request documents or additional datapoints later without accidentally rebilling blocks that were already covered inside the deduplication window.

<Tip>
  Store `requestId` values. `GET /v2/company/{requestId}` retrieves the latest result and refreshes signed document URLs without starting a new billable request.
</Tip>

## Included documents

Some official documents are included when a matching data block has already been requested or deduplicated. Inclusion is country-specific and document-specific.

Use the live pricing page or `GET /v2/pricing` to know whether a document is included with a block or billed standalone.

## Budget caps

Use `maxBudget` to cap total spend for a `/v2/company` request. If not every requested block fits, Topograph prioritizes blocks in this order:

1. Blocks that cover `company` (highest priority)
2. Blocks that cover `legalRepresentatives`
3. Blocks that cover `ultimateBeneficialOwners`
4. Blocks that cover `shareholders`
5. Blocks that cover `subsidiaries`

Blocks that exceed the remaining budget are omitted or marked as failed with `budget_exceeded`, while fulfilled datapoints continue normally.

```json theme={null}
{
  "countryCode": "FR",
  "id": "932884117",
  "dataPoints": ["company", "ultimateBeneficialOwners", "shareholders"],
  "maxBudget": 200
}
```

<Info>
  Use `GET /v2/pricing` before submitting budget-capped requests when your application needs to predict which blocks will fit.
</Info>

## Retrieve pricing programmatically

Use `GET /v2/pricing` to retrieve country-specific availability and pricing in your application.

```bash theme={null}
curl --request GET \
  --url 'https://api.topograph.co/v2/pricing?countryCode=FR' \
  --header 'x-api-key: <api-key>'
```

The response includes:

* Data blocks and the datapoints each block covers.
* Mode availability for verification and onboarding.
* Whether a mode is authoritative.
* Included document metadata.
* Flat per-datapoint availability for quick lookups.
* Variable-pricing markers when final document or register costs are known only at request time.

## Best Practices

<AccordionGroup>
  <Accordion title="Check prices before requesting">
    Use the live pricing page for human review and `/v2/pricing` for runtime decisions.
  </Accordion>

  <Accordion title="Leverage 24h deduplication">
    Split requests across your flow when useful. Duplicate covered blocks within the deduplication window are not charged again.
  </Accordion>

  <Accordion title="Store request IDs">
    Always store the `requestId` from your requests. You can use it to retrieve the same data later at no additional cost, regardless of when you make the follow-up request.
  </Accordion>

  <Accordion title="Bundle data and documents">
    When a document is included with a data block, requesting them together can simplify your flow.
  </Accordion>
</AccordionGroup>

## Account billing

<Info>
  Manage credits, payment methods, and invoices from the Topograph dashboard. For custom plans or high-volume usage, contact support.
</Info>