Reliability, Errors, and Pagination

Use this guide when your integration needs to handle partial results, pagination, and failed calls.

Check errors before reading results

Inspect the transport outcome, any JSON-RPC error, the MCP result's isError flag, and the tool payload's error object. An outer success does not guarantee a successful query. Check all layers before consuming results.

If error is present, do not interpret an empty entities or rows array as a successful zero-result answer. Preserve error.code, error.message, any response_status, and request_id when available.

These recommendations describe client handling; they are not an exhaustive server error-code contract. A client or connector can reject invalid arguments before they reach the server, so a validation failure may have no server request ID.

A successful profile response does not establish that every requested field or card was retrieved. Unknown or unavailable selections can be omitted without an error. Validate selections against cb_reference and distinguish missing fields/cards from explicit empty results. Use supported positive limits; do not rely on out-of-range inputs being rejected or normalized consistently.

Search pagination

cb_search_query returns entities and may include count. The count is the reported number of matches, not the number returned on this page.

Keep the collection, filters, fields, ordering, and limit unchanged between pages. Set after_id to the UUID of the last entity in the preceding page. Include identifier in selected fields.

Recommended loop:

1. Check errors and validate the result shape.
2. If the successful page is empty, end the traversal.
3. Process entities, deduplicating by UUID.
4. Read the last entity UUID and request the next page using that cursor.
5. Stop and mark the traversal incomplete if a cursor repeats, a page makes no progress, a request fails, or your page/time budget is reached.

Do not infer completion solely because a page contains fewer rows than requested. Access-dependent caps may affect the effective page size. Use counts as a cross-check; do not assume counts or records remain frozen across requests. This guide does not promise snapshot isolation or cursor lifetime.

Entity-card pagination

For cb_entity_get, scope card_ids to one card and pass field_ids=[] to minimize top-level fields. An identifier may still be included.

On the initial call, related_entity_limit guides distribution across selected lookup cards; it is not a strict total-row cap. The combined response can exceed the requested budget. Specify cards explicitly and enforce application-level row or payload safeguards. With after_id, the value requests a page size for exactly one card. A single card returns at most 100 entities per request; card and access limits can lower that number. Increasing the budget cannot override every card limit; use structured search or a reviewed compiled search when needed. Omitting card_ids selects one card per target collection, not every readable card. A card's has_more_entities indicates that a continuation may be needed, including when results were clipped to a budget; it is not a remaining-record count.

When has_more_entities=true, request the same single card with after_id set to the last related entity's identifier UUID. In the labeled response, find the property with field_id="identifier" and read value.uuid.

End on an explicit false flag or a successful empty page for the requested card. A missing card, missing flag, or repeated cursor is an unresolved traversal, not proof of completeness. Apply the same error, duplicate, and progress checks as search pagination.

Example: continue a funding-round card

First resolve the organization:

{"query":"Cohere","collection_ids":"organizations","limit":5}

Select the intended organization from the autocomplete results and use its identifier. Resolve the example company again in your workflow rather than assuming its identifier.

Call cb_entity_get:

{"entity_id":"34b73a99-d4cb-4bc5-8641-6db4fd2782b8","entity_def_id":"organization","field_ids":[],"card_ids":["funding_rounds_list"],"related_entity_limit":2}

Copy the last related entity's identifier UUID into the next request's after_id; preserve all other arguments. Do not reuse a cursor from another card or host entity.

Expert answers and previews

cb_expert_query_answer accepts one question. Its output includes columns, rows, row_count, and truncated. A non-null answered_question describes a narrower question that was answered; show that scope to the user.

If truncated=true, label the returned rows as partial. If explicitly false, the tool reports no truncation at its row limit; this does not prove that the question's interpretation or underlying coverage is exhaustive. If truncated is missing, treat its status as unknown. The current input does not expose a row limit, field selection, deduplication switch, or continuation cursor. Asking for “the next page” in a new natural-language question is not cursor pagination.

A build-search preview may be partial: preview_limit controls inline rows. Review the returned compiled search and use cb_search_query for subsequent pages. Preserve recursive query items rather than flattening them into predicates.

Unexpected zero results

A successful zero-result search says no records matched that request under the caller's access. It does not establish that the real-world category is empty.

Check each predicate's field reference. Identifier-valued fields require valid UUIDs or permalinks, not display names. Loosen one filter at a time to diagnose the request; label the revised scope clearly instead of presenting broader results as satisfying the original filters.

For relationship filters, a related entity collection is not necessarily the relationship collection required by a subquery. Use a compiled, reviewed search or a tested relationship example. Do not construct a subquery by replacing a flat predicate's collection name.

Limits and support

Call cb_metering_get_state to inspect the current user’s Crunchbase data-token allowance: limit, used and available amounts, status, period, affected tools, warnings, and upcoming_meter_refresh when available. It does not enumerate all rate limits or access restrictions. Treat missing amounts and status="unknown" as unknown, not unlimited. A meter reading is not a reservation for future calls.

Log your own invocation ID and timestamp alongside the tool name, elapsed time, outcome, and server request ID when present. Do not rely on the server ID alone as your application's unique key. Keep credentials and unnecessary response data out of logs.

For persistent failures, contact your Crunchbase account team or Customer Success Manager with the timestamp, client/version, tool, redacted arguments, error details, and request ID. Specific limits and support commitments depend on your arrangement.

See Building a Crunchbase MCP Integration and Known MCP Limitations.

If a successful result reports that the data-token allowance was exhausted, present that result and explain that subsequent affected data calls are unavailable until allowance is restored. Do not discard a successful result solely because it consumed the remaining allowance.

These instructions are for MCP tools. REST Entity Lookup parameters such as before_id, card_field_ids, and a REST API user key are not inputs to cb_entity_get. Use the connected tool’s schema, not REST examples, when forming an MCP call.