<!-- https://pricto.dev/docs/limites · Spanish version: https://pricto.dev/docs/limites.md -->

# Limits and costs

You pay per data point delivered, in credits. One credit is one product's price at one store. Every response says what it cost and what you have left.

## Credits per operation

| Operation | MCP tool | Credits |
|---|---|---|
| `GET /v1/products/search` | `search_products` | 1 per page of up to 20 results; 0 when nothing is found |
| `GET /v1/products` | — | 1 per 20 products returned |
| `GET /v1/products/{product_id}` | — | 1 |
| `GET /v1/products/{product_id}/prices` | `get_prices` | 1 per retailer offer returned |
| `GET /v1/products/{product_id}/history` | `get_price_history` | 1 per 30 points per series (minimum 1 per series) |
| `POST /v1/prices/compare` | `compare_prices` | 1 per price in the matrix (product × retailer with data) |
| `POST /v1/prices/batch` | — | 1 per offer price returned; items not found cost 0 |
| `GET /v1/offers` | `list_offers` | 1 per offer returned |
| `GET /v1/offers/{offer_id}` | — | 1 |
| `GET /v1/offers/{offer_id}/history` | — | 1 per 30 points (minimum 1) |
| `GET /v1/retailers` | — | 0 |
| `GET /v1/retailers/{retailer_id}` | — | 0 |
| `GET /v1/stores` | — | 0 |
| `GET /v1/categories` | — | 0 |
| `GET /v1/brands` | — | 0 |
| `GET /v1/coverage` | `get_coverage` | 0 |
| `GET /v1/countries` | — | 0 |
| `GET /v1/fx` | — | 0 |
| `GET /v1/status` | — | 0 |
| `GET /v1/public/coverage` | — | 0 |
| `GET /v1/account` | — | 0 |
| `GET /v1/usage` | — | 0 |
| `POST /v1/data-requests` | `request_data` | 0 |

The same thing costs the same over API, MCP or CLI. Errors are never charged.

## Plans and limits

| Plan | Price per month | Credits per month | Requests per second | Requests per day | History |
|---|---|---|---|---|---|
| Free | USD 0 | 100 | 1 | 300 | 30 days |
| Builder | USD 29 | 15,000 | 5 | no daily limit | 365 days |
| Pro | USD 99 | 75,000 | 15 | no daily limit | full |
| Business | USD 299 | 300,000 | 40 | no daily limit | full |
| Scale | USD 999 | 1,500,000 | 100 | no daily limit | full |
| Sandbox | Free | Not charged | 5 | 5,000 (and 60 per minute) | Sample data |

Pay as you go: USD 3 per 1,000 credits, from USD 10; they last 12 months from your last purchase. Full pricing at [/precios](/precios) and, for machines, at [/pricing.json](/pricing.json).

Every response carries the `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers. Past the limit, the API answers `429` with `Retry-After` (see [Errors](/docs/errores#rate_limited)).

## Control spending

- `max_credits`: a cap per call. The response is cut to fit (cheapest or most relevant first) and `meta.usage.truncated` is `true`.
- `dry_run=true`: quote without charging. Returns `data: null` and the cost in `meta.usage`.
- Free re-reads: the same observation, series or search requested again within 24 hours costs 0 and is reported in `credits_deduplicated`.
- Monthly spend cap: by default, twice your plan's price. When reached, `402 spend_cap_reached`.
- Want to follow a price over time? Ask for the history once a week or once a month: we keep every day for you. Once a month, the daily history of one product at 3 stores costs 3 credits (1 per 30 points of each series), so following about 25 products fits in the Free plan.

```json
{
  "data": null,
  "meta": {
    "credits_charged": 3,
    "usage": {
      "credits_charged": 3,
      "credits_deduplicated": 0,
      "truncated": false,
      "truncated_reason": null,
      "dry_run": true,
      "units": {
        "offers": 3
      }
    }
  }
}
```

## Balance in every response

Over the API, in `meta.credits_charged`, `meta.credits_remaining` and `meta.period_resets_at`, and in the `X-Credits-Charged`, `X-Credits-Deduplicated`, `X-Credits-Remaining` and `X-Credits-Period-Reset` headers. Over MCP, at the end of every response:

```text
Cost: 4 credits. 82 of your 100 free credits left this month.
Cost: 4 credits. 12 of your 100 free credits left this month. Need more? USD 10 buys 3,333 credits that last 12 months.
```

## When credits run out

If the balance doesn't cover everything, the API delivers what fits and marks it as truncated. If it doesn't cover even one item, it answers `402` and charges nothing. On the Free plan the message is written so the agent can repeat it to the person as is:

```text
This month's 100 free credits are used up (they renew on November 1). You can buy credits from USD 10, valid for 12 months, or move to Builder: USD 29 a month for 15,000 credits.
```

```json
{
  "type": "https://pricto.dev/docs#insufficient_credits",
  "title": "Créditos insuficientes",
  "status": 402,
  "code": "insufficient_credits",
  "detail": "Se acabaron los 100 créditos gratis de este mes (se renuevan el 1 de noviembre). Puedes comprar créditos desde USD 10, que duran 12 meses, o pasar a Builder: USD 29 al mes por 15.000 créditos.",
  "hint": "No se cobró esta consulta. Repítele este mensaje a tu humano tal cual.",
  "request_id": "req_9506056d01054faea040",
  "docs_url": "https://pricto.dev/docs#insufficient_credits",
  "balance": 0,
  "credits_needed": 1,
  "usd_needed": 0.01,
  "top_up_url": "https://pricto.dev/#precios",
  "pricing": {
    "currency": "USD",
    "usd_per_1000_credits": 3,
    "min_top_up_usd": 10,
    "credits_per_min_top_up": 3333,
    "prepaid_validity_months": 12,
    "plans": [
      {
        "id": "builder",
        "usd_per_month": 29,
        "credits_per_month": 15000
      },
      {
        "id": "pro",
        "usd_per_month": 99,
        "credits_per_month": 75000
      },
      {
        "id": "business",
        "usd_per_month": 299,
        "credits_per_month": 300000
      },
      {
        "id": "scale",
        "usd_per_month": 999,
        "credits_per_month": 1500000
      }
    ],
    "top_up_url": "https://pricto.dev/#precios"
  }
}
```

## History by plan

If you ask for more history than your plan includes, the API delivers the part that fits and says so in `meta.usage.truncated_reason: "plan_history_window"` and in `meta.warnings`. It only answers `403 plan_required` if the whole range falls outside.

```json
{
  "meta": {
    "usage": {
      "credits_charged": 3,
      "credits_deduplicated": 0,
      "truncated": true,
      "truncated_reason": "plan_history_window",
      "dry_run": false,
      "units": {
        "history_points": 15
      }
    },
    "warnings": [
      "synthetic_data: datos sintéticos de ejemplo / synthetic sample data",
      "truncated: tu plan incluye 30 días de historial; se entrega desde 2026-09-24."
    ]
  }
}
```