[{"data":1,"prerenderedAt":42},["ShallowReactive",2],{"docs:rendered-article:\u002Fdocs\u002Fpublic\u002Fguides\u002Frate-limits-credits":3},{"path":4,"slug":5,"title":8,"description":9,"category":6,"categoryLabel":10,"order":11,"status":12,"family":13,"subfamily":13,"content":14,"html":15,"examplesHtml":16,"excerpt":17,"readTimeMinutes":18,"headings":19,"examplesHeadings":36,"lastUpdated":13,"endpointId":13,"requiredFlag":13,"relatedArticlePaths":37,"badge":13},"\u002Fdocs\u002Fguides\u002Frate-limits-credits",[6,7],"guides","rate-limits-credits","Rate limits & credits","Understand the credit model, rate limits, and strategies to optimize API costs.","Guides",25,"updated",null,"\nEvery request costs between 0 and 4 credits depending on the endpoint. Most errors, stale data, and status checks are always free.\n\n## You're never charged for\n\n- **Errors**\n  all 4xx and 5xx responses cost 0 credits, except `404` which depends on the endpoint (see the pricing catalog).\n- **Check and Usage endpoints**\n  always 0 credits, designed for testing and decision-making before spending.\n\nYou can test the API freely before committing credits.\n\n> [!IMPORTANT]\n> **When your workspace reaches 0 credits, the free Check endpoints are paused too.** A call to `POST \u002Fv2\u002Ffetch\u002Fpersons\u002Fcheck` or `\u002Fv2\u002Ffetch\u002Fcompanies\u002Fcheck` then returns `402 NO_CREDITS` instead of a result, because no enrichment can follow until you top up. Status and result endpoints stay open: `GET \u002Fv2\u002Fusage`, `GET \u002Fv2\u002Fflags`, the Search `available-fields` endpoints, and webhook polling (`GET \u002Fv2\u002Fwebhooks\u002F:webhookId`) keep working so you can still read your balance and retrieve already-paid results. [Top up →](\u002Fsettings\u002Fbilling?tab=credits)\n\n## Per-endpoint pricing\n\nThe full credit-cost matrix lives in your dashboard. It covers every scenario (cache hit, live scrape, 404 cache, 404 live), async refund rules, and plan gating:\n\n> **[Open the API pricing catalog →](\u002Fsettings\u002Fbilling?tab=api-pricing)**\n>\n> One row per endpoint, one badge per scenario. Updated automatically with the gateway runtime, so what you read there is what gets billed.\n\nThe catalog also explains the **async billing model** in detail: how credits are charged at request creation and refunded automatically based on the outcome (API error, 404 on Search\u002FContact, 404 on Live endpoints). Refunds are auditable in the [Webhook Events](\u002Flogs\u002Fevents) dashboard.\n\n> [!NOTE]\n> **Webhook delivery failures are not refunded.** When your webhook URL is invalid, returns an error, times out, or is unreachable (`webhook-url-invalid`, `webhook-url-errored`, `webhook-url-timeout`, `webhook-url-unreachable`), the credit is kept because the data was successfully fetched. The job is reported as `succeeded` with a `deliveryStatus` field naming the delivery problem, and the `result` is populated, poll `GET \u002Fv2\u002Fwebhooks\u002F:webhookId` to retrieve it.\n\n## Rate limits\n\nTwo rate limits apply per workspace:\n\n| Limit | Scope | Description |\n| ----- | ----- | ----------- |\n| Minute limit | Workspace | Maximum requests per minute (e.g. 60 req\u002Fmin) |\n| Daily limit | Workspace | Maximum requests per day (Enterprise only, disabled by default) |\n\nYou can also set per-key rate limits to cap individual integrations below the workspace maximum. See [API key management](\u002Fdocs\u002Fguides\u002Fapi-key-management#3-set-rate-limits-optional) for details.\n\nWhen a rate limit is exceeded, the API returns `429 Too Many Requests`. Check the `quotas` object in any response to see your current usage:\n\n::: code-group [Rate limit response]\n```json [JSON]\n\"minuteRateLimit\": {\n  \"limit\": 60,\n  \"used\": 58,\n  \"left\": 2,\n  \"nextReset\": \"2025-01-15T09:31:00.000Z\"\n}\n```\n:::\n\nFor retry strategies on `429`, see [Error handling & retries](\u002Fdocs\u002Fguides\u002Ferrors-retries#when-to-retry).\n\n## Agent, MCP, and dashboard usage\n\nNot every credit-consuming action shows up as the same kind of usage event:\n\n- **Agent LLM turns** consume credits, but they do **not** hit the gateway directly and do **not** count toward gateway RPM.\n- **Agent tool calls** use the same gateway endpoints as the REST API. They consume endpoint credits and **do** count toward gateway RPM when the endpoint itself is RPM-metered.\n- **MCP calls** use the same credits and the same rate-limit rules as the REST API.\n- **Polling and status-only endpoints** such as `GET \u002Fv2\u002Fusage` and `GET \u002Fv2\u002Fwebhooks\u002F:webhookId` stay free and do **not** affect gateway RPM.\n\nIn the dashboard, the **Usage channels** section is the best view to understand where credits are going across Agent, MCP, and API usage. The request analytics tabs remain HTTP-request-centric on purpose.\n\n## Save credits\n\n**Check before you fetch.** Call the free Check endpoint first to see if a profile exists and when it was last updated. Then decide: cached fetch (1 credit) or live scrape (2 credits). See [Data freshness](\u002Fdocs\u002Fguides\u002Fdata-freshness) for the full strategy.\n\n**Use Search for bulk discovery.** 1 credit per search, up to 100 results per request. Find matching profiles first, then fetch only the ones you need.\n","\u003Cp>Every request costs between 0 and 4 credits depending on the endpoint. Most errors, stale data, and status checks are always free.\u003C\u002Fp>\n\u003Ch2 id=\"youre-never-charged-for\">You’re never charged for\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Cstrong>Errors\u003C\u002Fstrong>\nall 4xx and 5xx responses cost 0 credits, except \u003Ccode>404\u003C\u002Fcode> which depends on the endpoint (see the pricing catalog).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Check and Usage endpoints\u003C\u002Fstrong>\nalways 0 credits, designed for testing and decision-making before spending.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>You can test the API freely before committing credits.\u003C\u002Fp>\n\u003Cdiv class=\"markdown-alert markdown-alert-important\">\u003Cp class=\"markdown-alert-title\">\u003Csvg class=\"octicon octicon-report mr-2\" viewBox=\"0 0 16 16\" version=\"1.1\" width=\"16\" height=\"16\" aria-hidden=\"true\">\u003Cpath d=\"M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z\">\u003C\u002Fpath>\u003C\u002Fsvg>Important\u003C\u002Fp>\u003Cp>\u003Cstrong>When your workspace reaches 0 credits, the free Check endpoints are paused too.\u003C\u002Fstrong> A call to \u003Ccode>POST \u002Fv2\u002Ffetch\u002Fpersons\u002Fcheck\u003C\u002Fcode> or \u003Ccode>\u002Fv2\u002Ffetch\u002Fcompanies\u002Fcheck\u003C\u002Fcode> then returns \u003Ccode>402 NO_CREDITS\u003C\u002Fcode> instead of a result, because no enrichment can follow until you top up. Status and result endpoints stay open: \u003Ccode>GET \u002Fv2\u002Fusage\u003C\u002Fcode>, \u003Ccode>GET \u002Fv2\u002Fflags\u003C\u002Fcode>, the Search \u003Ccode>available-fields\u003C\u002Fcode> endpoints, and webhook polling (\u003Ccode>GET \u002Fv2\u002Fwebhooks\u002F:webhookId\u003C\u002Fcode>) keep working so you can still read your balance and retrieve already-paid results. \u003Ca href=\"\u002Fsettings\u002Fbilling?tab=credits\" target=\"_blank\" rel=\"noopener\">Top up →\u003C\u002Fa>\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"per-endpoint-pricing\">Per-endpoint pricing\u003C\u002Fh2>\n\u003Cp>The full credit-cost matrix lives in your dashboard. It covers every scenario (cache hit, live scrape, 404 cache, 404 live), async refund rules, and plan gating:\u003C\u002Fp>\n\u003Cblockquote>\n\u003Cp>\u003Cstrong>\u003Ca href=\"\u002Fsettings\u002Fbilling?tab=api-pricing\" target=\"_blank\" rel=\"noopener\">Open the API pricing catalog →\u003C\u002Fa>\u003C\u002Fstrong>\u003C\u002Fp>\n\u003Cp>One row per endpoint, one badge per scenario. Updated automatically with the gateway runtime, so what you read there is what gets billed.\u003C\u002Fp>\n\u003C\u002Fblockquote>\n\u003Cp>The catalog also explains the \u003Cstrong>async billing model\u003C\u002Fstrong> in detail: how credits are charged at request creation and refunded automatically based on the outcome (API error, 404 on Search\u002FContact, 404 on Live endpoints). Refunds are auditable in the \u003Ca href=\"\u002Flogs\u002Fevents\" target=\"_blank\" rel=\"noopener\">Webhook Events\u003C\u002Fa> dashboard.\u003C\u002Fp>\n\u003Cdiv class=\"markdown-alert markdown-alert-note\">\u003Cp class=\"markdown-alert-title\">\u003Csvg class=\"octicon octicon-info mr-2\" viewBox=\"0 0 16 16\" version=\"1.1\" width=\"16\" height=\"16\" aria-hidden=\"true\">\u003Cpath d=\"M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z\">\u003C\u002Fpath>\u003C\u002Fsvg>Note\u003C\u002Fp>\u003Cp>\u003Cstrong>Webhook delivery failures are not refunded.\u003C\u002Fstrong> When your webhook URL is invalid, returns an error, times out, or is unreachable (\u003Ccode>webhook-url-invalid\u003C\u002Fcode>, \u003Ccode>webhook-url-errored\u003C\u002Fcode>, \u003Ccode>webhook-url-timeout\u003C\u002Fcode>, \u003Ccode>webhook-url-unreachable\u003C\u002Fcode>), the credit is kept because the data was successfully fetched. The job is reported as \u003Ccode>succeeded\u003C\u002Fcode> with a \u003Ccode>deliveryStatus\u003C\u002Fcode> field naming the delivery problem, and the \u003Ccode>result\u003C\u002Fcode> is populated, poll \u003Ccode>GET \u002Fv2\u002Fwebhooks\u002F:webhookId\u003C\u002Fcode> to retrieve it.\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"rate-limits\">Rate limits\u003C\u002Fh2>\n\u003Cp>Two rate limits apply per workspace:\u003C\u002Fp>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Limit\u003C\u002Fth>\n\u003Cth>Scope\u003C\u002Fth>\n\u003Cth>Description\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>Minute limit\u003C\u002Ftd>\n\u003Ctd>Workspace\u003C\u002Ftd>\n\u003Ctd>Maximum requests per minute (e.g. 60 req\u002Fmin)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Daily limit\u003C\u002Ftd>\n\u003Ctd>Workspace\u003C\u002Ftd>\n\u003Ctd>Maximum requests per day (Enterprise only, disabled by default)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003Cp>You can also set per-key rate limits to cap individual integrations below the workspace maximum. See \u003Ca href=\"\u002Fdocs\u002Fguides\u002Fapi-key-management#3-set-rate-limits-optional\" target=\"_blank\" rel=\"noopener\">API key management\u003C\u002Fa> for details.\u003C\u002Fp>\n\u003Cp>When a rate limit is exceeded, the API returns \u003Ccode>429 Too Many Requests\u003C\u002Fcode>. Check the \u003Ccode>quotas\u003C\u002Fcode> object in any response to see your current usage:\u003C\u002Fp>\n\u003Cdiv class=\"docs-code-group\">\u003Cdiv class=\"docs-code-group-header\">\u003Cspan class=\"docs-code-group-title\" data-static-title>Rate limit response\u003C\u002Fspan>\u003Cdiv class=\"docs-code-group-actions\">\u003Cspan class=\"docs-code-group-lang\">JSON\u003C\u002Fspan>\u003Cbutton type=\"button\" class=\"docs-code-group-copy\" data-copy-code=\"true\">\u003Csvg width=\"14\" height=\"14\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\u003Crect width=\"14\" height=\"14\" x=\"8\" y=\"8\" rx=\"2\" ry=\"2\"\u002F>\u003Cpath d=\"M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2\"\u002F>\u003C\u002Fsvg>\u003C\u002Fbutton>\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"docs-code-group-panel active\" data-tab=\"0\" role=\"tabpanel\">\u003Cpre class=\"shiki shiki-themes github-light github-dark\" style=\"--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e\" tabindex=\"0\" data-language=\"json\">\u003Ccode class=\"language-json\">\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#032F62;--shiki-dark:#9ECBFF\">\"minuteRateLimit\"\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">  \"limit\"\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">60\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">  \"used\"\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">58\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">  \"left\"\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">2\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">  \"nextReset\"\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#032F62;--shiki-dark:#9ECBFF\">\"2025-01-15T09:31:00.000Z\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\n\u003C\u002Fdiv>\u003C\u002Fdiv>\n\u003Cp>For retry strategies on \u003Ccode>429\u003C\u002Fcode>, see \u003Ca href=\"\u002Fdocs\u002Fguides\u002Ferrors-retries#when-to-retry\" target=\"_blank\" rel=\"noopener\">Error handling & retries\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"agent-mcp-and-dashboard-usage\">Agent, MCP, and dashboard usage\u003C\u002Fh2>\n\u003Cp>Not every credit-consuming action shows up as the same kind of usage event:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Agent LLM turns\u003C\u002Fstrong> consume credits, but they do \u003Cstrong>not\u003C\u002Fstrong> hit the gateway directly and do \u003Cstrong>not\u003C\u002Fstrong> count toward gateway RPM.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Agent tool calls\u003C\u002Fstrong> use the same gateway endpoints as the REST API. They consume endpoint credits and \u003Cstrong>do\u003C\u002Fstrong> count toward gateway RPM when the endpoint itself is RPM-metered.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>MCP calls\u003C\u002Fstrong> use the same credits and the same rate-limit rules as the REST API.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Polling and status-only endpoints\u003C\u002Fstrong> such as \u003Ccode>GET \u002Fv2\u002Fusage\u003C\u002Fcode> and \u003Ccode>GET \u002Fv2\u002Fwebhooks\u002F:webhookId\u003C\u002Fcode> stay free and do \u003Cstrong>not\u003C\u002Fstrong> affect gateway RPM.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>In the dashboard, the \u003Cstrong>Usage channels\u003C\u002Fstrong> section is the best view to understand where credits are going across Agent, MCP, and API usage. The request analytics tabs remain HTTP-request-centric on purpose.\u003C\u002Fp>\n\u003Ch2 id=\"save-credits\">Save credits\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>Check before you fetch.\u003C\u002Fstrong> Call the free Check endpoint first to see if a profile exists and when it was last updated. Then decide: cached fetch (1 credit) or live scrape (2 credits). See \u003Ca href=\"\u002Fdocs\u002Fguides\u002Fdata-freshness\">Data freshness\u003C\u002Fa> for the full strategy.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Use Search for bulk discovery.\u003C\u002Fstrong> 1 credit per search, up to 100 results per request. Find matching profiles first, then fetch only the ones you need.\u003C\u002Fp>\n","","Every request costs between 0 and 4 credits depending on the endpoint. Most errors, stale data, and status checks are always free. You're never charged for - Errors all 4xx and...",3,[20,24,27,30,33],{"id":21,"title":22,"level":23},"youre-never-charged-for","You're never charged for",2,{"id":25,"title":26,"level":23},"per-endpoint-pricing","Per-endpoint pricing",{"id":28,"title":29,"level":23},"rate-limits","Rate limits",{"id":31,"title":32,"level":23},"agent-mcp-and-dashboard-usage","Agent, MCP, and dashboard usage",{"id":34,"title":35,"level":23},"save-credits","Save credits",[],[38,39,40,41],"\u002Fdocs\u002Fguides\u002Fproduction-checklist","\u002Fdocs\u002Fguides\u002Ferrors-retries","\u002Fdocs\u002Fguides\u002Fdata-freshness","\u002Fdocs\u002Fguides\u002Fwhich-endpoint-should-i-use",1785860237234]