# Usage and billing

> What counts as a Soldgraph API request, what each marketplace costs, the free requests and the monthly allowance on each plan, and how to track your usage.

## What counts

**A search that completes is one request.** That includes a search with no results and a search served from the cache.

These are free:

- Failed searches. A failed job has `credits: 0`.
- A page past the last one. It comes back complete with no rows and `credits: 0`.
- Errors, like a `401` or a `429`.
- Job polls.
- Retries of the same search with the same `Idempotency-Key`. You get the same request back, so you're charged once.

Each response's `credits` field shows how many requests it cost. One credit is one request.

A bigger eBay page (`count` up to 200) is still one search and one request.

A [batch](https://soldgraph.com/docs/api/batches.md) costs one request per search in it that completes. Creating the batch and polling it are free. Searches in a batch that fail or are rejected cost nothing.

While a search is pending, it holds 1 request of your allowance. If the job fails, you get it back.

## Cost by marketplace

| Marketplace | Countries | Cost per search | Notes |
| --- | --- | --- | --- |
| eBay | `us`, `uk`, `ca`, `au`, `de`, `fr`, `it`, `es` | 1 request | Keyword search of sold and active listings on eBay's US, UK, Canada, Australia, Germany, France, Italy and Spain sites, with condition and price filters. Prices come back in each site's currency. One page per request: 40 rows, or up to 200 with `count`. Cached for 15 minutes. Displayed prices may differ from what the buyer paid. |
| Poshmark | `us`, `ca` | 1 request | Keyword search of sold and active listings on Poshmark US and Canada, with condition and price filters and cursor pagination. Prices come back in each site's currency. One source page per request, cached for 15 minutes. Displayed prices are listing asks, not what the buyer paid. |
| Mercari | `us` | 1 request | US keyword search of sold and active listings, up to 100 rows per page, with condition, price, category and brand filters and cursor pagination. One source page per request, cached for 15 minutes. Displayed prices may differ from what the buyer paid. |
| Depop | `us`, `uk`, `au`, `ca` | 1 request | Keyword search of active listings only, from sellers in the US, UK, Australia or Canada, up to 100 rows per page, with condition and price filters and cursor pagination. Prices come back in each country's currency. One source page per request, cached for 15 minutes. Headline prices can include buyer fees. |
| Whatnot | `us`, `ca` | 1 request | Buy It Now active listings only, from sellers in the US or Canada, up to 24 rows per page. Prices come back in each country's currency. Condition, price, category and seller-supplied grading filters; cursor pagination. Cached for 15 minutes. No public sold search or final sale prices. |
| TCGplayer | `us` | 1 request | Product catalog search and up to five recently observed sales for an exact product ID. Catalog Market Price is an estimate; sales are individual transactions, not complete history. Cached for 15 minutes. |
| OfferUp | `us` | 1 request | US local active listings around a ZIP code or coordinates, 5 to 50 miles (25 to 5,000 for vehicles), about 50 per page with repeats removed across pages. Condition, price, category, sort and vehicle filters. Item lookup adds posted date, coordinates, seller, shipping and vehicle details. Cached for 15 minutes. No sold search or final sale prices. |
| Facebook Marketplace | `us` | 1 request | US local active listings around a ZIP code or coordinates, searched from the nearest Facebook Marketplace city, up to about 24 per search. Radius, price, condition, delivery, listing age and sort filters, each checked against what Facebook applied. Item lookup adds description, condition, coordinates, delivery and photos. One page per search, no seller details, cached for 15 minutes. No sold search or final sale prices. |
| Vinted | `us`, `uk`, `fr`, `de`, `it`, `es`, `nl`, `be`, `pt`, `at`, `lu`, `ie`, `pl`, `se`, `cz`, `dk`, `fi`, `lt`, `hu`, `ro`, `sk`, `hr`, `gr`, `si`, `lv`, `ee` | 1 request | Keyword search of active listings on Vinted's US, UK and 24 European sites, 96 rows per page, with condition, brand, category and price filters and four sort orders, each checked against what Vinted applied. Prices come back in each site's currency. Rows carry the item price and the total with Vinted's buyer protection fee. Item lookup adds description, colour, category, photos and the seller's rating. Up to 10 pages per search, cached for 15 minutes. No sold search or final sale prices. |

If a marketplace ever costs more than one request per search, we'll list it here before you can call it.

## Free requests

A new account starts with **100 free requests**, no credit card required. They're a one-time grant and don't refill. When it runs out, new searches use your [extra requests](#extra-requests) if you have any. Otherwise they return `429 quota_exceeded` with an `upgrade_url`, until you buy requests or pick a plan.

Accounts made before October 9, 2026 keep the free allowance they signed up with: 100 requests in a rolling 30-day window.

## Monthly allowance

| Plan | Requests a month | Price |
| --- | --- | --- |
| Lite | 2,000 | $9 |
| Starter | 5,000 | $19 |
| Pro | 20,000 | $49 |
| Business | 100,000 | $149 |
| Scale | 350,000 | $499 |

Your allowance covers a rolling 30-day window, not a calendar month. When it runs out, new searches use your [extra requests](#extra-requests) if you have any. Otherwise they return `429 quota_exceeded` until older usage leaves the window or you move to a larger plan. There are no automatic overage charges.

Every plan allows **60 API calls per minute per account**, shared across your keys. Searches and job polls both count. See [Rate limits](https://soldgraph.com/docs/api/rate-limits.md).

Choose or change a plan on the dashboard's [Billing](/app/billing) page. Paid plans renew monthly. When you cancel, you keep the plan until the month you paid for ends.

## Extra requests

You can buy requests without a plan. You pay once, not monthly.

- **With no plan:** $10 per 1,000, from 1,000 at a time.
- **On a paid plan:** $3 per 1,000, from 5,000 at a time.
- They're used only after your plan's allowance, or your free requests, run out.
- They don't expire, and they stay on your account if you change or cancel your plan.
- A failed search gives its extra request back.

## Tracking usage

- The [dashboard](/app) shows your usage against your plan: over the last 30 days, or of your free requests.
- [Logs](/app/logs) lists every request with its cost, marketplace and country.
- Each search or job response's `credits` field shows what it cost.
- [Billing](/app/billing) shows your plan, its renewal date and the extra requests you have left.
- `GET /v1/usage` returns the same numbers to your code. It's free, but counts toward the per-minute rate limit:

```bash
curl https://api.soldgraph.com/v1/usage -H "Authorization: Bearer $SOLDGRAPH_KEY"
```

```json
{
  "plan": "starter",
  "used": 1240,
  "limit": 5000,
  "remaining": 3760,
  "extra_requests": 0,
  "window": "rolling_30_days",
  "shared_allowance": false,
  "rate_limit_per_minute": 60
}
```

`used` and `remaining` are what the API checks before it accepts a search. On a free plan, `used` includes linked accounts that share the allowance, and `shared_allowance` is `true`. `limit` and `remaining` are `null` on unlimited plans.

With free requests, `window` is `one_time`: `limit` is the 100 free requests, and `used` never goes down as time passes. Otherwise `window` is `rolling_30_days`.