Discover Frameworks
Check which entity and insight combinations have data before you run a query, and see the options each one offers.
Overview
The Discover Frameworks tool takes the candidate entities and insights you found with Search Entities and Search Insights. It tells you which combinations can be built into a framework. For each one it returns everything you need to write a precise Framework-to-Insight request: location and date resolutions, aggregations, filters, date coverage and metric columns.
This is a discovery tool and does not consume MCP tokens. Nothing is billed until you run Framework-to-Insight.
Input / Output
| Input | A list of entities (each with its carc_id and representation) and a list of insight_ids |
| Output | The frameworks that can be built, each with its available options. If none can be built, related entities that do have data |
Every entity is paired with every insight. For example, 2 entities and 3 insights give 6 combinations. A single call can check up to 16 combinations. Duplicates are removed before the count.
How It Fits the Workflow
- Find candidates. Use Search Entities to find the entity (for example,
"Walmart") and Search Insights to find the metric (for example,"Card Spend"). You can pass the entity to Search Insights to rank the insights that have data for it. - Discover Frameworks. Pass your best candidates to see which combinations have data and what each one supports.
- Run the query. Use the options returned to build a Framework-to-Insight request.
This replaces trial and error. You no longer have to run a paid query only to find out that an entity has no data for an insight, or that a filter or resolution isn't supported.
Writing the Input
Pass each entity's carc_id and representation exactly as returned by Search Entities. The representation is the entity type, such as retailer, company, or ticker. The same carc_id with a different representation refers to a different entity.
{
"entities": [
{ "carc_id": 28368, "representation": "retailer" }
],
"insights": [626]
}
What You'll Get
Discover Frameworks returns the combinations you can build, in the order you requested them. It skips a combination if the insight has no data for the entity, your account doesn't have access, or an ID is incorrect.
| Field | What it tells you |
|---|---|
| Entity | The entity's carc_id, representation, and name |
| Insight | The insight's ID, name, and whether it's normalized |
| Location resolutions | Available geographic levels, such as us or state |
| Date resolutions | Available time grains at each geographic level, such as day, week, month, or quarter |
| Aggregations | Supported options, such as sum or mean, and the default Framework-to-Insight uses if you don't specify one |
| Filters | Each supported filter's key, label, value count (option_count), and a random sample of up to 10 values |
| Dates | The first and last dates with data (min_date and max_date), plus any data lag applied to your account |
| Metric columns | The metrics the insight returns |
Check how recent the data is
Check max_date before using a framework to answer a question about recent activity. If multiple insights share a name, compare their max_date values to see which has the freshest data.
Get the full list of filter values
sample_values is a random sample. If option_count is larger than the number of values shown, or both fields are empty, pass the filter key to get_filter_options to get the full list. Use the returned values exactly as written.
When Nothing Can Be Built
If none of the requested combinations has data, the response lists alternatives: related entities that have data for the insights you requested.
- Parent: The company that owns the requested brand, ticker, app, or website.
- Child: A brand, ticker, app, or website owned by the requested company.
- Sibling: Another entity owned by the same company.
Run Discover Frameworks again with an alternative to check its coverage and options. A parent company's total covers a different series from an individual brand's, so name the entity you actually used when sharing results.
When to Use
- Before every Framework-to-Insight call to confirm coverage and get the exact parameters.
- When deciding which of several candidate entities or insights to use.
- When checking whether the data covers a specific period.
- When you need the supported filters and resolutions.
Discover Frameworks is free. Run it first so the paid query uses a combination with data and supported options.
Limits
- Maximum 16 entity × insight combinations per call. If you exceed the limit, narrow the request to your best candidates and try again.
- Minimum one entity and one insight per call.
- Rate limit: 30 calls in a burst and 350 per hour. See MCP Rate Limits.