Skip to main content
What it cannot do, how to read the numbers, the limits, and what to do about errors.

What it does not do

  • Create, edit, publish or delete content.
  • Recompute a chart or analytics for parameter values other than the published ones.
  • Read content that is not published to Exploratory Server, such as projects that exist only in Exploratory Desktop. Use the separate Desktop MCP for those.

Numbers and their conditions

  • Numbers are the values as published.
  • A chart published on its own returns only the first 100 rows of the data used to draw it. Do not add the rows up as a total.
  • A viewer who changes parameters in the browser sees different results. MCP does not return those results.
  • Each chart and analytics result states the conditions of its computation: the aggregation, the chart filters, context.parameters and context.data_as_of.
  • query_dataset returns dataset.version and dataset.updated_at.

Limits

Errors and what to do

A tool that fails returns a result with isError: true and a JSON body. The body has error_code and message, and sometimes url and details. For a bad argument, details.field names the argument. For SERVER_BUSY:
  • Try again in a few seconds.
  • If it happens twice in a row, stop and try again later.
  • For the hourly export limit, wait up to an hour.
query_dataset reports a bad query differently. It returns error.code, error.message and error.field, with their own codes. For example:
  • DATASET_NOT_FOUND
  • ACCESS_DENIED
  • CHANNEL_DISABLED
  • DATASET_ACCESS_DENIED (joins)
  • DATASET_NOT_QUERYABLE
  • INVALID_COLUMN
  • INVALID_FILTER
  • AMBIGUOUS_COLUMN
  • JOIN_TYPE_MISMATCH
  • QUERY_LIMIT_EXCEEDED
  • QUERY_TIMEOUT
When the query engine is busy, it returns RATE_LIMIT_EXCEEDED or QUERY_ENGINE_UNAVAILABLE. Try again in a few seconds. When result.has_more is true, narrow the filters, aggregate, or use dataframe_export. dataframe_export uses error_code like the other tools. For a bad query, it returns INVALID_PARAMETER. The query’s own code is in details.code.

Rate limit

If you send more than 120 requests in a minute, you get HTTP 429 with RATE_LIMITED. Wait one minute. If one address sends more than 30 refused API keys within 15 minutes (counted per IPv4 address, or per IPv6 /64 range), you get HTTP 429 with the message “Too many failed API key attempts. Try again later.” A valid key is not counted. Fix the key and try again later.