API: Limits & budgets

Budgets and rate limits keep an agent from running away with your account. They belong to your account: every key you make shares them, across the REST API, MCP and the CLI. Making more keys doesn't add capacity.

Most limits grow with your plan. This page doesn't list those numbers, because they can change. Your live numbers are always in two places:

• ListingView Settings → API Keys, under Today's usage.

• GET /api/v1/usage. Use the CLI's listingview usage get or the MCP tool get_account_usage.

A few caps are the same on every plan. This page names them where they apply.

For what you'll see in the app when a budget runs out (the banner, the email and the in-app notice), see Using the ListingView API, MCP server & CLI.

Read your budgets with /usage

GET /usage is the source of truth. It is free, and it needs the research:read scope, which every access preset except Publisher includes. It shows the same numbers as Settings and the response headers.

curl https://api.listingview.io/api/v1/usage \
  -H "Authorization: Bearer $LISTINGVIEW_API_KEY"

Each budget window reports used, limit, remaining, reset_at and exhausted. When part of the answer can't be read right now, it is listed in unavailable and stale is true; ask again in a moment.

Three windows help an agent plan Etsy-draft and research work before it starts:

• etsy_draft_deletes: Etsy drafts deleted through the API today. It resets at midnight UTC.

• staged_batches: api_staged, your open staged batches against the cap of 18, and open_drafts, your account's open-draft slots (20, shared with the app). Both count what is open now, so they free up when a batch is submitted or discarded, not at a set time (reset_at is null). Shown on the Plus plan and higher.

• research_refresh: your account's share of today's research refreshes (see Research freshness below). It resets at midnight UTC. It is left out while ListingView has fresh Etsy reads switched off.

These three are in /usage only. Today's usage in Settings doesn't show them. /usage also shows preset_writes (new presets today) and imports (image imports today).

Calls that cost credits also send your remaining credits in the headers X-LV-Credits-Remaining, X-LV-Credits-Limit, X-LV-Credits-Reset and X-LV-Credits-Window. They describe whichever window, daily or monthly, has the least left. Research calls that read Etsy live send X-LV-EtsyCalls-* headers for your Etsy-call budget the same way. Successful answers carry no RateLimit-* headers.

When limits reset

Daily limits reset at midnight UTC. Monthly limits reset at the start of each month, UTC. Every budget error tells you when it frees up: details.resets_at, and retry_after in seconds.

API credits

Your account has a daily and a monthly credit budget. Each call costs credits by how heavy it is. Reading your own data is free. The API reference shows each route's cost (x-lv-credits), and so does describe.

• A replayed call (same idempotency key) costs nothing.

• With a test key, writes and AI copy are dry runs and cost nothing. Reads are real and cost what they cost with a live key. See Rehearse with a test key in API: Getting started.

• Most failed calls are refunded. A NOT_FOUND answer is still charged.

• A keyword lookup that matched nothing at all gets its credit back: found: false with no ListingView data, a matched_count of 0 and no example listings. Any other found: false is charged.

Other daily budgets

• Uploads: files started through the upload API, delivery files included. Files you already have don't count.

• Image imports: images fetched from links. An image you already have costs less than a new one.

• New presets: 100 presets created or copied through the API a day, the same on every plan (preset_writes_daily). Edits don't count.

• Preset deletes: 20 a day, the same on every plan. It isn't shown in /usage; the refusal (DATA_BUDGET_EXCEEDED with the reason preset_deletes_daily) tells you when it resets.

Uploads also count against your asset-library storage. A full library answers STORAGE_QUOTA_EXCEEDED. API: Uploads covers every way to add files.

Etsy drafts

Creating Etsy drafts needs the Plus plan or higher. Three limits apply:

• items per job,

• drafts per shop per day,

• drafts per day across your whole account.

A job is accepted whole or refused whole. It is never cut short to fit. /usage shows all three under etsy_drafts.

ListingView also has a daily capacity for agent-made Etsy drafts across all sellers. When it is used up, calls answer RATE_LIMITED with details.reason: "etsy_capacity", and /usage shows etsy_drafts.capacity_exhausted: true. This isn't your plan's limit. Try again after midnight UTC.

Staged batches

A staged batch waits in Saved listings until it is submitted or discarded. It has no expiry, so an old batch stays until someone acts on it.

• 18 open staged batches. Your account can have up to 18 open batches staged through the API. They sit inside your account's 20 open-draft slots, which the app shares. When none are free, staging answers CONFLICT with details.reason: "draft_slots_full", details.scope (api_staged or open_drafts, whichever ran out) and both windows. Submit or discard a batch to free one.

• Items per batch. A staged batch can't hold more items than one Etsy-draft job allows on your plan. That is checked when you stage, each time you add items, and again when you submit. Too many items answers DATA_BUDGET_EXCEEDED with details.reason: "etsy_drafts_job"; split them into several batches.

• Daily limits count at submit. Staging uses none of your daily Etsy-draft limits. They count on the day you submit. A submit refused for a daily limit leaves the batch staged, with nothing lost.

• Edits. Edits and discards of staged batches share the rate limit the app uses for saving drafts: 30 writes a minute per account. Past it you get RATE_LIMITED with the reason draft_writes. Send all the changes to a batch in one edit.

Deleting Etsy drafts

You can delete up to 50 Etsy drafts a day through the API, per account. The count is in /usage as etsy_draft_deletes. Past the cap, deletes answer DATA_BUDGET_EXCEEDED with details.reason: "etsy_draft_deletes_daily" until midnight UTC. Only drafts your ListingView Bulk Create made can be deleted. Stage Etsy drafts, review them in ListingView, then submit covers the rules.

Per-call caps

Some calls have a fixed cap on how much one request can carry. These caps are the same on every plan, and describe lists their current values.

A lookup that asks for live inventory on more than 25 ids is refused with VALIDATION_FAILED and the code live_inventory_limit, never trimmed. A reprice that would store more than 32 KB answers 413 VALIDATION_FAILED with details.reason: "too_large" and details.limit_kind: "confirmation_payload". Split it into smaller reprices. Publish and reprice live listings covers the confirm step.

Live writes (push, publish and bulk reprice) also have an hourly and a daily limit per account, one unit per listing. A push that needs more units than are left answers RATE_LIMITED with the reason live_writes_hourly or live_writes_daily.

Research freshness

Etsy's terms limit how old the Etsy data that ListingView shows can be: 6 hours for listings, 24 hours for shops. Research answers keep to that without making you wait for a full refresh.

Refresh on serve. When an answer includes listing or shop rows older than that, ListingView refreshes only the rows it is about to return. Listings are refreshed in one batched Etsy call per page; shops take one call each. This applies to keyword example listings, listings search, shops search, a shop's listings and listing details.

• Gone listings are dropped. A listing Etsy no longer returns as active is left out and counted in rows_removed. It is never shown stale.

• Listings ListingView knows aren't public are dropped too, and counted in rows_removed. If ListingView can't check that for a page, the whole page is refused with a retryable 503 (database_unavailable).

• A shared, short-lived cache. Refreshed rows are cached for every ListingView account, for up to 6 hours (listings) or 24 hours (shops) from when ListingView fetched them. The next request for the same row is served from the cache, with no Etsy call. Listing details never reads or writes this cache.

• Nothing is written back. A refresh only changes what you're served. ListingView's research data isn't updated by your request.

• Your credits don't pay for refreshes. Refreshes draw on a daily refresh budget shared across ListingView, and each account gets a daily share of it. Your share is research_refresh in /usage. Research prices are unchanged.

Pointer-only rows. When a row can't be refreshed, it comes back as a pointer: content: "pointer_only". A pointer carries the listing id, its Etsy URL, ListingView's own estimates and estimates_as_of, but no Etsy title, price, image or tags. pointer_reason says why. When the reason is temporary, refresh_retry_after says how many seconds to wait.

When fresh reads are switched off. If ListingView pauses fresh Etsy reads, stale rows are withheld rather than turned into pointers, and counted in rows_withheld_stale. A shop analysis that has never run answers SERVICE_UNAVAILABLE with the reason refresh_paused, etsy_unavailable or refresh_unavailable; a shop analysed before serves its stored result with sync.refresh_blocked.

Every list answer counts what it served: rows_refreshed, rows_cached, rows_pointer_only, rows_removed and rows_withheld_stale. rows_withheld_stale is 0 in normal operation. Listing details carries no counts: it uses the same pointer shape and no longer answers DATA_STALE, and a listing ListingView knows isn't public answers NOT_FOUND.

Broad keywords. A one-word keyword like "mug" matches millions of listings. Its figures are worked out from a sample: a keyword answer carries corpus.sampled and corpus.sample_size, and metrics.active_listing_count_is_lower_bound when the count stopped at 200,000. A listings search carries summary.sampled, sample_size, matched_count and matched_count_is_lower_bound. Every search stops after 12 seconds: past that you get SERVICE_UNAVAILABLE with details.reason: "deadline_exceeded". It is retryable after retry_after; a narrower search is faster.

Tags. Tags ListingView's data can't key, such as tags with accents, emoji or symbols, or more than 4 words, are left out of tag answers.

Shop search. match is name, sells or any. If the sells lookup fails, the first page comes back with partial: ["sells"] and no next page; a later page answers a retryable 503, which you retry with the same cursor.

Keyword counts. Keyword answers carry up to four counts, each named for what it counts:

• monthly_listing_count: listings that matched in ListingView's last monthly snapshot, by tag or title.

• active_listing_count: active listings in ListingView's data now that match the phrase in the title or a tag.

• matched_count: results of a listings search.

• etsy_competing_listing_count: Etsy's own total. competing_source says where it came from.

A count with no value is left out rather than sent as null. Corpus answers also carry next_refresh_expected. describe explains each count and field.

AI tokens

AI copy spends AI tokens from your ListingView balance, not API credits. Check the balance with GET /api/v1/usage/ai-tokens. When the balance is too low, the call is refused with AI_TOKENS_INSUFFICIENT before any AI runs. See Tokens & Credits for how AI tokens work in the app.

Rate and concurrency limits

Separate from budgets, the API limits how fast you send requests and how many run at once. These limits are the same on every plan.

• Too many requests in a short time: RATE_LIMITED with details.reason: "burst", plus scope, window and limit. An account can send 20 requests a second, 600 a minute and 12,000 an hour across all its keys. One key can send 10 a second and 300 a minute.

• Too many requests running at once: RATE_LIMITED with details.reason: "concurrency". Each key can have 3 requests in flight, and each account 4 across all its keys, so one busy key always leaves a slot for your other keys. details says whether the key or the account limit was hit.

• Their own limits. AI calls (ai_concurrency, at most 2 at once per account), image imports (import_concurrency) and unfinished uploads (uploads_in_flight, at most 300) have their own limits.

• Test keys have their own burst and concurrency limits, apart from your live keys.

• Limiter down. If ListingView can't check these limits, it refuses rather than lets the request through: SERVICE_UNAVAILABLE with the reason rate_limiter_unavailable, retryable.

A RATE_LIMITED error is retryable: wait retry_after seconds, then try again. Run requests one after another rather than all at once.

The errors you'll see

Higher plans have bigger budgets. See Plans & Billing for what each plan includes.

Related features

• API: Getting started: keys, test keys, idempotency keys and the error shape

• API: Connect AI apps: MCP calls share these budgets

• API: Command-line tool: listingview usage get and exit code 5

• API: Uploads: the upload and image-import budgets in practice

• Stage Etsy drafts, review them in ListingView, then submit: staged batches and Etsy-draft deletes

• Publish and reprice live listings: reprices and the confirm step

• Error codes: every error code and what to do about it

• Tokens & Credits: AI tokens used for AI copy

• Plans & Billing: which plan includes what

• Using the ListingView API, MCP server & CLI: the seller guide to keys, presets and Etsy drafts