Limits and errors

How machine access is bounded

Looking and taking are bounded differently. A person reading a property, a firm or a person on screen in the Greenfinch app is doing what your plan or your geography licence already paid for, and is not rationed (see Fair use in the app). A taking — a record delivered to a program, over REST, through the MCP connector, to a webhook or Zapier — is bounded at three levels, which answer three different questions:

API and connector usage is bounded by limits that scale with the size of your Enterprise plan: a larger licensed territory carries a larger records allowance, and the daily limits are derived from it rather than chosen separately. Your order states the numbers, and you can read them back at any time — see Where you see your usage.

Level 1 · Request rate

Each API key has one counter covering every REST endpoint and the MCP endpoint together. Windows are fixed 60-second periods.

• The limit follows your organization's current plan, checked on every request.
• An organization can hold 10 active keys, so its combined ceiling is 10 times the per-key limit.
• Greenfinch can set a different per-minute rate for your organization, which then replaces the plan default on every key and assistant connection you hold. (Rolling out.)
• Before a key is checked, requests are also limited to 1,000 per minute from one IP address. It only matters if many keys share one outbound address.
• Searching is bounded here and nowhere else. A search result is a summary — an identifier, an address, a one-line description, a count — so it is never a taking and never draws your records allowance. Discovery is throttled; looking something up is not.
• A daily request ceiling also applies to Enterprise keys and assistant connections: 50,000 requests per UTC day across all of them together, which Greenfinch can raise, lower or clear for your organization. A request past it is refused with DAILY_REQUEST_LIMIT_EXCEEDED. A Team organization has no daily ceiling unless one is set for it. Your Limits and usage page shows the ceiling in force and today's count. (Rolling out.)

A request over the per-minute limit is answered 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789402860
Cache-Control: no-store
Content-Type: application/json

{
  "success": false,
  "error": "Too many requests — this key's limit of 300 requests a minute is spent. Retry in 23s.",
  "meta": {
    "code": "rate_limited",
    "retryAfterSeconds": 23,
    "limit": {
      "name": "requests_per_minute",
      "level": 1,
      "value": 300,
      "used": 300,
      "resets_at": "2026-09-15T06:01:00Z"
    }
  }
}

A request over the daily ceiling is also 429, with a different code, because retrying sooner cannot help — the count restarts at midnight UTC:

{
  "success": false,
  "error": "Requests per day: this organization's limit of 50,000 requests a day, across every API key and AI assistant connection, is used (50,000 today). Resets 2026-09-16T00:00:00.000Z.",
  "meta": {
    "code": "DAILY_REQUEST_LIMIT_EXCEEDED",
    "retryAfterSeconds": 21600,
    "limit": {
      "name": "requests_per_day",
      "level": 1,
      "value": 50000,
      "used": 50000,
      "resets_at": "2026-09-16T00:00:00.000Z"
    }
  }
}

• Wait Retry-After seconds (the same number as meta.retryAfterSeconds). X-RateLimit-Reset is when the window ends, in Unix seconds. These headers are sent on 429 responses.
• If the rate limiter itself is unavailable, requests are refused rather than let through: 503 with meta.code rate_limit_unavailable and a Retry-After. Retry with backoff.

Level 2 · Daily data limits

Separate from request rates, each kind of data that leaves has a daily limit, so an automation that goes wrong cannot take out or change more than your organization expects. Days are UTC and reset at midnight UTC.

Three layers can apply to each kind, and the lowest one in force wins:

• The two daily figures for records taken move with your allowance, so a larger allowance raises them automatically. The per-key figure stops one runaway program inside a day; the organization figure means spreading a pull across many keys does not outrun it either.
• An admin can also switch agent pipeline changes off entirely; tools then refuse with MCP_QUALIFICATION_DISABLED.
• Retired 14 September 2026: AGENT_QUALIFICATION_DISABLED and DAILY_CAP_REACHED. greenfinch_update_lead_status used to answer this same limit with codes of its own; it now returns the standard codes, like every other pipeline tool. Nothing returns the retired pair any more.
• Refusals include the numbers — usedToday, cap, remainingToday and resetsAt — so a job can plan rather than retry.
• Check where you stand before a run: greenfinch_describe_workspace reports the reveal and delivery limits, and greenfinch_get_transition_cap the pipeline limit.

Level 3 · The records allowance

Every Enterprise order states a records allowance: how many distinct records your programs may take per billing period. It is the commercial bound on machine access, it is sized to your plan, and it is the one limit of the three that your order — not a setting — carries. Your period is the one in your contract; where none is recorded, it is the UTC calendar month.

What counts as a record

A record is one property, one firm or one person, delivered in full. A taking is a record delivered to a program. A record is taken when it is:

• returned in full by a REST API call;
• returned in full by an MCP tool — whether the assistant signed in as a person or with an API key, because the same data leaves either way;
• pushed to your CRM, to a webhook, or through Zapier;

A lead bundle is a taking of the property plus each distinct firm and person inside it. A bundle carrying two firms and two people is five records — the property, both firms, both people.

These never count, and never draw the allowance:

How it is counted

• Once per record, per period, across every door. A record taken twice in the same period — re-read by an assistant, re-synced nightly, re-exported in a full run — counts once. Repetition inside the period is free, and at the period boundary the count starts again from zero.
• One allowance, every door. REST, the MCP connector, CRM pushes, webhooks and Zapier all draw the same number. There is no door through which a record leaves uncounted, and so no cheaper door to move a job to.
• The allowance never widens a licence. A record outside your licensed area still has to be unlocked with credits first, exactly as in the app; once unlocked, taking it counts like any other record. The allowance governs how much may leave, never what you may see.
• An initial load is a separate, one-time allowance. If your contract loads a whole territory in its first period, the order can carry a one-time initial-load allowance alongside the recurring one. It is shown separately and is spent before the recurring allowance.
• No credits are charged for taking. Credits keep paying for seeing — research, unlocking a record outside your licensed area, revealing a person on their own, deep research, email drafts.

What happens at the allowance

Your order says which of two things happens, and the allowance endpoint tells you which applies to you:

• Taking stops until the period resets. Calls that would deliver a record are refused with RECORDS_ALLOWANCE_EXCEEDED, naming the allowance, what has been used and the reset time. Looking in the app is completely unaffected — your people carry on reading properties, firms and people as before, because that is what the licence bought. Search, lists and the pipeline keep working too.
• Or the excess is invoiced at the per-record price your order states, up to the ceiling it states. Nothing is charged without your order saying so, and every response to a successful taking reports how much overage the period has accrued, so an invoice can never arrive unseen.

Team plans have no order and no records allowance. Their per-prospect deliveries keep the existing meter — a free monthly allowance, then one credit each — described under Lead bundles.

Where you see your usage

What every refusal says

Every refusal caused by a limit names the limit, its level and when it resets — in the message a person reads and in a structured limit object a program can branch on. The shape is the same on REST, on MCP tools and in the status of an export job.

{
  "success": false,
  "code": "ACCOUNT_DAILY_CAP_EXCEEDED",
  "error": "Records taken per day: a daily maximum of 1,000, derived from your records allowance, is used (1,000 today). Resets 2026-09-16T00:00:00Z.",
  "meta": {
    "code": "ACCOUNT_DAILY_CAP_EXCEEDED",
    "limit": {
      "name": "records_taken_per_day",
      "level": 2,
      "layer": "greenfinch_admin",
      "derived": true,
      "value": 1000,
      "used": 1000,
      "resets_at": "2026-09-16T00:00:00Z"
    }
  }
}

{
  "success": false,
  "code": "RECORDS_ALLOWANCE_EXCEEDED",
  "error": "Records allowance: the period ending 2026-09-30T23:59:59Z is fully used. Taking is paused until the allowance resets; looking in the app is unaffected. Overage is not enabled on this order.",
  "meta": {
    "code": "RECORDS_ALLOWANCE_EXCEEDED",
    "limit": {
      "name": "records_allowance",
      "level": 3,
      "value": 10000,
      "used": 10000,
      "remaining": 0,
      "period_ends_at": "2026-09-30T23:59:59Z",
      "overage_enabled": false,
      "overage_price_per_record_usd": null
    }
  }
}

• level is 1 (request rate), 2 (daily data) or 3 (the records allowance).
• layer appears on level 2 only: greenfinch_admin, organization or key. When two layers hold the same lowest value, layers lists both. It tells you whether it was your own key or the whole organization that ran out.
• derived appears on level 2 only, and only on a limit that can be worked out rather than typed in — today, records taken per day. true means the number that stopped you was computed from your records allowance, so the way to raise it is a larger allowance rather than asking for the number itself to be changed. It is omitted, rather than false, on limits that have no derived form at all.
• On an organization with overage enabled, a level-3 refusal arrives only at the ceiling the order states; below it, overage_enabled is true and successful takings report the overage accrued so far.
• The existing codes keep their names, so integrations written against them keep working; they gain the limit object. MCP tools carry the same object in their structured result and the same sentence in their text.
• Values shown here are illustrative. The numbers that apply to you are your order's and your admins', and are readable from the allowance endpoint.

Fair use in the app

The three levels above bound what a program takes. The Greenfinch app applies a separate fair-use bound on what one signed-in person opens: it counts the distinct property detail pages a person opens, warns when the pace stops looking like reading, and pauses property detail pages if it continues. Searching, lists, the pipeline and the API keep working throughout, and a pause lifts by itself.

• A person doing their job never meets it. The thresholds are set from how long it takes to actually read a property page, and a heavy prospecting day sits comfortably below them. They exist for one case only: a browser driven by a script, signed in as a person, used to read a territory page by page.
• Search results, map tiles and list views are not counted — those are how people find things.
• Your admins and Greenfinch are both notified if a pause ever fires, so nobody discovers it from a confused salesperson, and Greenfinch can clear it.
• The supported way to read a lot of properties is this API, within your allowance — not a browser driven by a script, which your order does not permit.

Credits

Credits pay for seeing a record you are not already licensed for, and for research. They are shared by your whole organization and charged the same whether an action happens in the app, through the API, or through an AI assistant. Nothing below is charged for delivering a record to a program — that is what the records allowance bounds instead.

greenfinch_get_price_sheet returns this list, greenfinch_get_credit_balance and GET /account the balance, and greenfinch_price_research quotes a research job before you run it. Running out of credits never triggers an automatic charge: the action is refused.

HTTP statuses

Error and refusal codes

On REST, read the code from meta.code, or from the top-level code for errors raised before the endpoint runs. On MCP, access errors use the same HTTP bodies, and tool refusals put the code in result.structuredContent.code with HTTP 200.

Access and account

Credits and limits

Coverage and visibility

Pipeline and write-back

Research, lists and search

Each tool's full list of refusal codes is on its card in the MCP tool reference. Protocol-level errors (invalid JSON, unknown tool, invalid arguments) are described on MCP connector.