Execute an analysis

Maps to: POST /v1/analyses/execute

Runs an analysis from a definition you send in the request, and returns the calculated data. This page documents the execute call itself; the building blocks it references are explained in Concepts, and the response shape in Output formats.

Endpoint

• Method / path: POST /v1/analyses/execute
• Body: an analysis definition (JSON)
• Response: the calculated data, one result block per series

Saved analyses. To run an analysis you saved earlier, use GET /v1/analyses/execute/{uuid} instead — same result format, no body needed.

CSV output. Append .csv to the path (e.g. POST /v1/analyses/execute.csv) for a flat CSV response. The body is unchanged. See Output formats.

Requests must be authenticated, and are subject to size and rate limits. Identical requests may be served from a short-lived cache.

Request structure

{
  "meta": { "version": "v1" },
  "data": {
    "id": "my-analysis",
    "title": "My Analysis",
    "queries": [
      {
        "id": "series-1",
        "entity":   { "...": "what to measure" },
        "period":   { "...": "over which dates" },
        "metrics_score_types": { "...": "which metrics and how to score them" },
        "filters":  [],
        "scoring":  "total",
        "moving_average": 1
      }
    ]
  }
}

The top level:

Field	Required	Description
meta	Yes	Envelope metadata — currently {"version": "v1"}.
data	Yes	The analysis definition.

The analysis (data):

Field	Required	Description
queries	Yes	One or more queries; each produces its own result series. They are calculated and returned together.
id	No	A label of your choosing, echoed back. Not interpreted by the service.
title	No	A human-readable name. Not interpreted by the service.

Query fields

Each query combines the building blocks below. Only entity, period, metrics_score_types and filters are needed for a meaningful result; the rest have defaults. Follow the links for the full explanation and rules of each.

Field	Required	Default	Purpose	Details
entity	Yes	—	What to measure (brand, sector, custom sector, industry, or an "all brands" expansion)	Regions, sectors & brands, Custom sectors & industries
period	Yes	—	The date range to cover	Periods & dates
metrics_score_types	Yes	—	Which metrics to return and the score type for each	Metrics, Score types & scoring
filters	Yes	[]	Audience / respondent filters (empty list for none)	Filters
scoring	No	total	Which base population to score against	Score types & scoring
moving_average	No	1	Rolling-average window, in days	Periods & dates
resample	No	none	Group results into larger time buckets (e.g. weekly)	Periods & dates
confidence_bound	No	none	Return a confidence bound instead of the point estimate	see below
id	No	none	A label for the series, echoed back in the result	—
title	No	none	A human-readable series name	—

Fields accepted but used only by the BrandIndex UI — API users can ignore them: uuid, visualization_attributes, is_market_scanner, properties_meta.

Confidence bounds

By default a query returns the point estimate for each metric. Set confidence_bound to return the upper or lower edge of a confidence interval instead:

{ "type": "upper", "percent": 95 }

• type — upper or lower.
• percent — the confidence level, an integer from 1 to 99.

To show both a value and its interval, run separate queries for the point estimate and each bound.

Response

The response mirrors the envelope and returns one result block per series (remember an "all brands" entity produces several blocks from one query). Each block carries its calculated data as a metric × date × perspective cube, plus metadata such as last_period_is_complete.

See Output formats for the full JSON and CSV specifications and how to read them.

Worked examples

Each example below is a complete request body to POST /v1/analyses/execute.

One brand, one metric, fixed dates

{
  "meta": { "version": "v1" },
  "data": {
    "id": "buzz-q1",
    "queries": [
      {
        "id": "acme-buzz",
        "entity": { "region": "us", "sector_id": 1, "brand_id": 1007 },
        "period": {
          "start_date": { "date": "2024-01-01" },
          "end_date":   { "date": "2024-03-31" }
        },
        "metrics_score_types": { "buzz": "net_score" },
        "filters": []
      }
    ]
  }
}

Several metrics, smoothed, rolling window

"Buzz, Reputation and Consideration for one brand over the last 90 days, with a 7-day moving average."

{
  "meta": { "version": "v1" },
  "data": {
    "queries": [
      {
        "id": "brand-health",
        "entity": { "region": "us", "sector_id": 1, "brand_id": 1007 },
        "period": {
          "start_date": { "days": 90 },
          "end_date":   { "days": 1 }
        },
        "metrics_score_types": {
          "buzz": "net_score",
          "reputation": "net_score",
          "consider": "positives"
        },
        "moving_average": 7,
        "filters": []
      }
    ]
  }
}

Brand vs. category benchmark (two queries)

{
  "meta": { "version": "v1" },
  "data": {
    "queries": [
      {
        "id": "brand",
        "entity": { "region": "us", "sector_id": 1, "brand_id": 1007 },
        "period": { "type": "year", "offset": 1, "amount": 1 },
        "metrics_score_types": { "impression": "net_score" },
        "resample": { "size": 1, "type": "month_from_day" },
        "filters": []
      },
      {
        "id": "sector-median",
        "entity": { "region": "us", "sector_id": 1, "is_median": true },
        "period": { "type": "year", "offset": 1, "amount": 1 },
        "metrics_score_types": { "impression": "net_score" },
        "resample": { "size": 1, "type": "month_from_day" },
        "filters": []
      }
    ]
  }
}

All brands in a sector (expansion)

The single "all brands" query expands into one result series per brand.

{
  "meta": { "version": "v1" },
  "data": {
    "queries": [
      {
        "id": "sector-ranking",
        "entity": { "brands_from_sector_id": 1, "region": "us", "only_active": true },
        "period": {
          "start_date": { "days": 30 },
          "end_date":   { "days": 1 }
        },
        "metrics_score_types": { "aided": "net_score" },
        "filters": []
      }
    ]
  }
}

Filtered by audience

"Purchase Intent among 18–34 year-olds, last complete month, scored against people aware of the brand."

{
  "meta": { "version": "v1" },
  "data": {
    "queries": [
      {
        "id": "young-adults-intent",
        "entity": { "region": "us", "sector_id": 1, "brand_id": 1007 },
        "period": { "type": "month", "offset": 1, "amount": 1 },
        "metrics_score_types": { "likelybuy": "positives" },
        "scoring": "aware",
        "filters": [
          { "definition_name": "profiles_us__age", "op": "in", "values": ["18-24", "25-34"] }
        ]
      }
    ]
  }
}

With a confidence bound

{
  "meta": { "version": "v1" },
  "data": {
    "queries": [
      {
        "id": "recommend-upper",
        "entity": { "region": "us", "sector_id": 1, "brand_id": 1007 },
        "period": {
          "start_date": { "date": "2024-01-01" },
          "end_date":   { "days": 1 }
        },
        "metrics_score_types": { "recommend": "net_score" },
        "resample": { "size": 7, "type": "calendar_day" },
        "confidence_bound": { "type": "upper", "percent": 95 },
        "filters": []
      }
    ]
  }
}

Quick reference

• Endpoint: POST /v1/analyses/execute (or GET /v1/analyses/execute/{uuid} for a saved analysis). Append .csv for CSV.
• Envelope: { "meta": {"version": "v1"}, "data": { "queries": [ … ] } }
• Required per query: entity, period, metrics_score_types, filters (may be []).
• Score type = which responses count; scoring = who is in the base.
• moving_average and resample are alternatives — resample wins.
• "All brands" entities and index inflate request size — watch the limits.
• Response data is a cube values[metric][date][perspective] — see Output formats.

Related

• Concepts
• Output formats
• Execute a saved analysis
• Guides