Reading Search Quota with the Clay CLI

Every clay searches query-mode run response includes a periodQuota object that shows how many search results the workspace has used in the current period. In the runs measured here, used rose by exactly the number of records returned, and the credit balance did not change.

What you will build

A script that runs three searches pages of different sizes and prints the quota after each one.

clay searches query-mode create  ->  searchId
    ↓
clay searches query-mode run <searchId> --limit <n>  (three times)
    ↓
periodQuota { limit, used, remaining, resetsAt }

AI Prompt

Using the Clay CLI, read the search quota after each page of a search.

Requirements:
- Each `clay searches query-mode run` response includes `periodQuota: { limit, used, remaining, resetsAt }` when a quota applies.
- Per the command help, result limits depend on the plan: Free is 50 per request, 50 per search, and 100 per 30 days; Trial is 50 per request, 50 per search, and 10,000 for the trial; Paid is 500 per request and up to 1,000,000 per 30 days; Legacy paid is 500 per request and up to 1,000,000 per year; Enterprise is 500 per request and up to 10,000,000 per 30 days.
- The workspace used here reports a `limit` of 10,000,000, which matches the Enterprise figure in the help text.
- The period is a rolling window and ages out daily at midnight UTC, per the help text.
- A search that reaches its quota returns `quota_exceeded` (exit 1). Do not retry until the period resets or the plan changes.
- Run the verification step below before finishing.

Using the Clay CLI, read the search quota after each page of a search.

Requirements:
- Each `clay searches query-mode run` response includes `periodQuota: { limit, used, remaining, resetsAt }` when a quota applies.
- Per the command help, result limits depend on the plan: Free is 50 per request, 50 per search, and 100 per 30 days; Trial is 50 per request, 50 per search, and 10,000 for the trial; Paid is 500 per request and up to 1,000,000 per 30 days; Legacy paid is 500 per request and up to 1,000,000 per year; Enterprise is 500 per request and up to 10,000,000 per 30 days.
- The workspace used here reports a `limit` of 10,000,000, which matches the Enterprise figure in the help text.
- The period is a rolling window and ages out daily at midnight UTC, per the help text.
- A search that reaches its quota returns `quota_exceeded` (exit 1). Do not retry until the period resets or the plan changes.
- Run the verification step below before finishing.

Prerequisites

The clay CLI on PATH, authenticated via clay login
jq

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Run three pages and print the quota

SID=$(clay searches query-mode create --query 'select from companies where industry = "Software Development"' | jq -r .searchId)
for n in 3 10 1; do
  clay searches query-mode run $SID --limit $n | jq -c --argjson n $n '{requested: $n, returned: (.data | length), used: .periodQuota.used, remaining: .periodQuota.remaining, limit: .periodQuota.limit, resetsAt: .periodQuota.resetsAt}'
done
clay credits balance | jq .balance

SID=$(clay searches query-mode create --query 'select from companies where industry = "Software Development"' | jq -r .searchId)
for n in 3 10 1; do
  clay searches query-mode run $SID --limit $n | jq -c --argjson n $n '{requested: $n, returned: (.data | length), used: .periodQuota.used, remaining: .periodQuota.remaining, limit: .periodQuota.limit, resetsAt: .periodQuota.resetsAt}'
done
clay credits balance | jq .balance

Real output on 2026-10-09:

{"requested":3,"returned":3,"used":52610,"remaining":9947390,"limit":10000000,"resetsAt":"2026-10-10T00:00:00.000Z"}
{"requested":10,"returned":10,"used":52620,"remaining":9947380,"limit":10000000,"resetsAt"
{"requested":1,"returned":1,"used":52621,"remaining":9947379,"limit":10000000,"resetsAt"

{"requested":3,"returned":3,"used":52610,"remaining":9947390,"limit":10000000,"resetsAt":"2026-10-10T00:00:00.000Z"}
{"requested":10,"returned":10,"used":52620,"remaining":9947380,"limit":10000000,"resetsAt":"2026-10-10T00:00:00.000Z"}
{"requested":1,"returned":1,"used":52621,"remaining":9947379,"limit":10000000,"resetsAt":"2026-10-10T00:00:00.000Z"}

used moved from 52610 to 52620 (+10) and then to 52621 (+1), matching the records returned. The credit balance was 393063 before and after.

2. Read the plan limits from the help text

clay searches --help | sed -n '/Result limits/,/contact their assigned/p'

clay searches --help | sed -n '/Result limits/,/contact their assigned/p'

Real output:

Result limits:
  Free        50 per request, 50 per search, 100 per 30 days (rolling; ages out daily at midnight UTC)
  Trial       50 per request, 50 per search, 10,000 for the trial duration
  Paid        500 per request, up to 1,000,000 per 30 days (rolling; ages out daily at midnight UTC)
  Legacy paid 500 per request, up to 1,000,000 per year (Starter, Explorer, Pro; resets January 1 UTC)
  Enterprise  500 per request, up to 10,000,000 per 30 days (rolling; ages out daily at midnight UTC)

For a higher limit, customers on other paid plans can contact Clay Support; Enterprise customers should
contact their assigned Clay GTME.

Result limits:
  Free        50 per request, 50 per search, 100 per 30 days (rolling; ages out daily at midnight UTC)
  Trial       50 per request, 50 per search, 10,000 for the trial duration
  Paid        500 per request, up to 1,000,000 per 30 days (rolling; ages out daily at midnight UTC)
  Legacy paid 500 per request, up to 1,000,000 per year (Starter, Explorer, Pro; resets January 1 UTC)
  Enterprise  500 per request, up to 10,000,000 per 30 days (rolling; ages out daily at midnight UTC)

For a higher limit, customers on other paid plans can contact Clay Support; Enterprise customers should
contact their assigned Clay GTME.

Only the Enterprise-sized figure was observed in a live response. The other plan limits are reported from the help text and were not exercised.

Verify the result

clay searches query-mode run <searchId> --limit 1 | jq '.periodQuota | {used, remaining}'

clay searches query-mode run <searchId> --limit 1 | jq '.periodQuota | {used, remaining}'

Expected: used is one higher than on the previous call for the same workspace, and remaining is one lower, when no other search ran in between.

How it works

Searches and credits are tracked separately. Reading a page of results adds the number of records returned to periodQuota.used, and the workspace credit balance is not touched. remaining is limit minus used, and resetsAt is the next midnight UTC boundary.

Common issues

The limit depends on the plan

A workspace on a different plan reports a different limit. Read periodQuota.limit from the response instead of hard coding 10,000,000.

Exhaustion is reported two ways

A page response carries hasMore and exhaustionReason (query_limit or no_more_results) when a search ends, and a workspace out of quota gets quota_exceeded. The quota-exceeded case was not triggered in this batch and is described from the command help.

Next steps

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "clay searches query-mode run <searchId> --limit 1 | jq '.periodQuota | {used, remaining}'"
  expected_result: "used is one higher and remaining one lower than the previous call, when no other search ran in between."

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "clay searches query-mode run <searchId> --limit 1 | jq '.periodQuota | {used, remaining}'"
  expected_result: "used is one higher and remaining one lower than the previous call, when no other search ran in between."