Data-Token Metering

Use this page to read Crunchbase data-token usage from MCP responses, track a workflow, and handle allowance errors. Data tokens measure Crunchbase data and Expert work; your AI provider measures text tokens separately.

Read the raw MCP tool result

Read data-token usage from the tool result's outer _meta object. It is separate from structuredContent, which contains the tool's data, and is not part of the tool's output schema.

This representative JSON-RPC response shows the location. The numbers are illustrative:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      { "type": "text", "text": "Retrieved profile." }
    ],
    "structuredContent": {
      "properties": [
        { "field_id": "identifier", "value": { "permalink": "crunchbase" } },
        { "field_id": "name", "value": "Crunchbase" }
      ],
      "cards": []
    },
    "isError": false,
    "_meta": {
      "cb/data_tokens": {
        "consumed": 20,
        "exhausted": false
      }
    }
  }
}

The business payload above is abbreviated to show two non-empty fields. If your MCP SDK returns the tool result directly, read toolResult._meta["cb/data_tokens"]. If you handle JSON-RPC yourself, read response.result._meta["cb/data_tokens"].

A returned consumed: 0 confirms zero tokens deducted for that invocation. An omitted consumed does not mean zero. For example, a metering outage can leave the deduction unconfirmed.

The metering entry is not guaranteed on every MCP response. It can be absent when metering does not apply to the caller, for free list writes (cb_list_create and cb_list_add_entities), or when a protocol or validation error prevents tool execution. An adapter can also drop _meta. Missing metadata alone does not prove that a request was free or the account has unlimited access.

Some connectors expose only content, structuredContent, and isError. Verify the connector used in production preserves the raw result's _meta; do not look for it inside the profile or search payload. If it is unavailable, report per-request usage as unknown. A balance check provides an account-level reading, not an exact replacement for missing per-request metadata.

Track a complete workflow

One prompt can produce several tool invocations. Usage metadata reports the deduction for that invocation, including charged nested data fetches. For example, an Expert response can already include an embedded profile or results preview in its reported deduction. Do not count those embedded results again as separate calls.

For a complete workflow:

1. Give each actual tool invocation its own application attempt ID.
2. Read and store its metering metadata before your adapter formats the result.
3. Add each known consumed amount once.
4. Count responses with missing amounts separately, so an incomplete total is not presented as exact.
5. Stop further affected data requests when a response reports exhaustion; inspect its result and error before deciding what to display.

This plain JavaScript helper takes a raw MCP tool result, not only its structuredContent:

const attempts = new Map();

function recordUsage(attemptId, toolResult) {
  // Avoid recording the same delivered result twice.
  if (attempts.has(attemptId)) return;

  const usage = toolResult._meta?.["cb/data_tokens"];
  const consumed = Number.isSafeInteger(usage?.consumed)
    && usage.consumed >= 0 ? usage.consumed : null;

  attempts.set(attemptId, {
    consumed,
    exhausted: typeof usage?.exhausted === "boolean"
      ? usage.exhausted
      : null
  });
}

function usageTotal() {
  const entries = [...attempts.values()];
  return {
    knownConsumed: entries.reduce(
      (sum, entry) => sum + (entry.consumed ?? 0), 0
    ),
    unknownAttempts: entries.filter(
      entry => entry.consumed === null
    ).length,
    exhaustionReported: entries.some(
      entry => entry.exhausted === true
    )
  };
}

Use a fresh attemptId for an actual retry. Identical arguments, repeated prompts, and cached results are not a guarantee of zero usage. A server request_id is useful for support, but is not a substitute for your application's invocation tracking.

This helper totals usage only. It does not decide whether the tool succeeded or whether an error response includes usable partial data. For that handling, see Reliability, Errors, and Pagination.

Check the allowance

Call cb_metering_get_state with {}. The check is free. Select the meter with meter_id: "data_mcp_tokens" from structuredContent.meters; do not assume it is always the first entry.

Representative payload, with illustrative amounts:

{
  "meters": [
    {
      "meter_id": "data_mcp_tokens",
      "label": "Data Tokens",
      "description": "Tracks the volume of Crunchbase data returned by data and expert tools.",
      "limitation_message": "If exhausted, data-returning tools (see related_tools) will be unavailable until reset.",
      "scope": "user_id",
      "period": "month",
      "limit": 100000,
      "used": 20,
      "available": 99980,
      "status": "available",
      "upcoming_meter_refresh": "2026-11-01T00:00:00+00:00",
      "related_tools": ["cb_entity_get", "cb_search_query"]
    }
  ]
}

The tool returns the caller's actual labels, amounts, reset time, and affected-tool list. The related_tools list above is abbreviated.

An empty meters array means no visible metered allowance was returned. It does not prove that all access restrictions are absent. Check the tool's error before using any meter reading.

A balance reading does not reserve tokens. Other connections for the same account can consume tokens between the check and your request. Before/after balance differences can include other requests or allowance changes. Use per-result metadata to attribute usage.

What contributes to the deduction?

For basic fields, missing/null values, blank text, and empty lists cost zero. A zero or false value counts. A non-empty object or list in one basic field counts once, rather than once per nested item. Display labels, response envelopes, and the assistant's final prose are not additional basic fields. A profile can retrieve more related data than the assistant displays; do not calculate the exact charge by counting the visible answer.

For Expert answers, counted response values use 10 tokens each for ordinary queries, 20 for window calculations without an aggregate, and 100 for queries that include a non-window aggregate such as a count, sum, or average. The selected rate applies to all counted values in that answer, not only calculated columns; the 100-token rate takes precedence when both kinds occur. This response-value rate does not multiply data retrieval or processing. Expert search definitions and titles use 10 tokens per counted value.

Expert counts values recursively in returned data: lists contribute their entries, objects contribute their populated values, and an entity identifier counts as one value. Empty strings and null values contribute none. Request IDs and other response-envelope fields do not add a response-value charge. Processing varies with the work performed, so a short response or zero matching rows does not imply a free Expert request.

The combined charge for an Expert response is capped at 200,000 tokens. This is a maximum, not a minimum. A separately fetched profile or results preview can add to the MCP invocation's total above that cap. Read the reported consumed amount instead of applying another cap in your client.

Handle allowance errors

Crunchbase applies charges automatically. Record the returned consumed amount, including when the result contains an error.

A usable response can consume only the remaining allowance. For example, a request calculated at 1,200 tokens with 500 available can return data with consumed: 500, exhausted: true. An exhaustion error with no usable data reports consumed: 0, exhausted: true.

A positive balance does not reserve tokens. Check the result and error separately: exhausted: false does not establish that the request succeeded.

Partial results, retries, and timeouts

An ordinary tool error with no usable data has no data charge. A metering error can still report a deduction; preserve any returned consumed amount. An empty structured search uses zero tokens; an Expert answer with no matching rows can still incur charges.

Keep and label usable partial data. Inspect structuredContent.error even when isError is false, and retain any reported deduction.

A timeout or disconnect can leave usage unknown. Completed work can still consume tokens, and a retry is a new invocation. Inspect destination state before retrying a write.

For error codes, retry rules, and support details, see Reliability, Errors, and Pagination.