Published indices

Read the published time series for one institutional-grade price index. Returns monthly values plus full methodology metadata. Snapshots are precomputed; this route never recomputes on the fly.

GET/v1/indices/{slug}$0.01

Path parameters

Name	Type	Description
`slug`required	string	One of: `eggs_cage_free_large_dozen`, `soda_12pk_12oz_cans`, `basket_low_income`, `basket_high_income`.

Query parameters

Name	Type	Description
`region`	stringdefault: `national`	One of `national`, `northeast`, `midwest`, `south`, `west`.
`from`	string	Start period as `YYYY-MM`. Defaults to today minus 12 months.
`to`	string	End period as `YYYY-MM`. Defaults to today's month.
`include_beta`	booleandefault: `false`	Include pre-inception trial-run snapshots published for methodology validation.
`include_revoked`	booleandefault: `false`	Include snapshots that were revoked after publication. Default off; toggle on for transparency / audit reads.
`include_preview`	booleandefault: `false`	Include `forced_hide` and `draft` snapshots. Internal use for QA.

ℹ

What the default response gives you

Out of the box you get the clean institutional view: publish_status equals auto or forced_publish, revoked = false, ordered by period ascending. That's the series an analyst should chart.

Request

curl 'https://api.mainmarket.com/v1/indices/eggs_cage_free_large_dozen?region=national&from=2025-06&to=2026-04'

Response

200 OKjson

{
  "data": [
    {
      "period": "2025-06",
      "value_usd": 4.92,
      "value_indexed": 100.00,
      "n_observations": 18420,
      "n_stores": 6822,
      "n_chains": 64,
      "coverage_score": 0.91,
      "publish_status": "auto",
      "flagged_for_review": false,
      "flag_reason": null,
      "revoked": false,
      "methodology_version": 2,
      "computed_at": "2025-07-02T03:14:18Z"
    },
    {
      "period": "2026-04",
      "value_usd": 5.23,
      "value_indexed": 106.30,
      "n_observations": 19210,
      "n_stores": 7012,
      "n_chains": 67,
      "coverage_score": 0.93,
      "publish_status": "auto",
      "flagged_for_review": false,
      "flag_reason": null,
      "revoked": false,
      "methodology_version": 2,
      "computed_at": "2026-05-02T03:11:09Z"
    }
  ],
  "meta": {
    "as_of": "2026-05-03T01:14:00Z",
    "slug": "eggs_cage_free_large_dozen",
    "name": "Eggs, Cage-Free, Large, Dozen",
    "description": "Average national price of one dozen large cage-free eggs.",
    "index_type": "single_sku",
    "method": "trimmed_mean",
    "source_methodology": "BLS-CPI inspired",
    "methodology_url": "https://api.mainmarket.com/methodology.md",
    "methodology_version": 2,
    "inception_period": "2025-06",
    "base_period": "2025-06",
    "base_value_usd": 4.92,
    "regions": ["national"],
    "constituents": [
      { "upc": "00071600051501", "name": "Vital Farms Pasture-Raised Large", "weight": 0.30 },
      { "upc": "00099482492700", "name": "Pete and Gerry's Organic Large", "weight": 0.25 }
    ],
    "chain_filter": null,
    "request_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
    "warning": null
  }
}

SnapshotRow fields (data[])

Name	Type	Description
`period`	string	Calendar month, YYYY-MM.
`value_usd`	number	Index value in USD (e.g. dollars per dozen, dollars per basket).
`value_indexed`	number \| null	Computed at query time from the index's frozen `base_value_usd`. Null while the index is in beta and no base has been chosen.
`n_observations`	integer	Distinct (store, product, day) rows used in the trimmed mean.
`n_stores, n_chains`	integer	Coverage breadth.
`coverage_score`	number	0.0–1.0 internal QA score for the period.
`publish_status`	string	One of `auto`, `beta`, `forced_publish`, `forced_hide`, `draft`.
`flagged_for_review, flag_reason`	mixed	Soft anomaly flag from the QA cron.
`revoked`	boolean	True when the snapshot was retracted after publication.
`methodology_version`	integer	Version of the formula used for this snapshot. Bumps invalidate older comparisons.
`computed_at`	timestamp	When the snapshot was written.

IndexMeta fields (meta)

Name	Type	Description
`as_of`	timestamp	Server time at request.
`slug, name, description`	string	Index identity.
`index_type`	string	One of `single_sku`, `multi_sku_same_format`, `basket_total_cost`.
`method`	string	Aggregation method label, e.g. trimmed_mean.
`source_methodology`	string \| null	Reference standard, e.g. 'BLS-CPI inspired'.
`methodology_url`	string	Stable URL to the full methodology doc.
`methodology_version`	integer	Current methodology version.
`inception_period, base_period`	string	Series-level period anchors (YYYY-MM).
`base_value_usd`	number \| null	USD value used as the index=100 anchor. Null while the index is in beta.
`regions`	string[]	Regions for which snapshots exist.
`constituents`	object[]	Per-product weights (UPC, name, weight). Used to reproduce the index locally.
`chain_filter`	object \| null	Optional chain inclusion/exclusion rules baked into this index.
`request_id`	uuid	Per-request id for support.
`warning`	string \| null	Soft warning, e.g. 'index is inactive: curation pending'.

ℹ

Beta values are unindexed

value_indexed is null on beta snapshots because no base has been chosen yet. Pre-inception trials are surfaced for methodology validation; chart them in absolute USD instead. See Indices methodology for the full pipeline.

Notable behavior

Snapshots are written by a cron job. This route is read-only and never recomputes — a 200 OK with empty data means the slug exists but no snapshots match the requested window.
When the index exists but is inactive (curation pending), the response is 200 OK with empty data and meta.warning set.
The default 12-month window is calendar-month based. For deep history, set from explicitly.

Errors

Name	Type	Description
`404`	Not Found	Slug is not a known published index.
`422`	Unprocessable Entity	`from` or `to` not `YYYY-MM`, or `region` not in the supported list.
`402`	Payment Required	Paid route — no payment proof.

Name

Type

Description

slugrequired

string

One of: eggs_cage_free_large_dozen, soda_12pk_12oz_cans, basket_low_income, basket_high_income.

Query parameters

Name	Type	Description
`region`	stringdefault: `national`	One of `national`, `northeast`, `midwest`, `south`, `west`.
`from`	string	Start period as `YYYY-MM`. Defaults to today minus 12 months.
`to`	string	End period as `YYYY-MM`. Defaults to today's month.
`include_beta`	booleandefault: `false`	Include pre-inception trial-run snapshots published for methodology validation.
`include_revoked`	booleandefault: `false`	Include snapshots that were revoked after publication. Default off; toggle on for transparency / audit reads.
`include_preview`	booleandefault: `false`	Include `forced_hide` and `draft` snapshots. Internal use for QA.

ℹ

What the default response gives you

Out of the box you get the clean institutional view: publish_status equals auto or forced_publish, revoked = false, ordered by period ascending. That's the series an analyst should chart.

Response

200 OKjson

{
  "data": [
    {
      "period": "2025-06",
      "value_usd": 4.92,
      "value_indexed": 100.00,
      "n_observations": 18420,
      "n_stores": 6822,
      "n_chains": 64,
      "coverage_score": 0.91,
      "publish_status": "auto",
      "flagged_for_review": false,
      "flag_reason": null,
      "revoked": false,
      "methodology_version": 2,
      "computed_at": "2025-07-02T03:14:18Z"
    },
    {
      "period": "2026-04",
      "value_usd": 5.23,
      "value_indexed": 106.30,
      "n_observations": 19210,
      "n_stores": 7012,
      "n_chains": 67,
      "coverage_score": 0.93,
      "publish_status": "auto",
      "flagged_for_review": false,
      "flag_reason": null,
      "revoked": false,
      "methodology_version": 2,
      "computed_at": "2026-05-02T03:11:09Z"
    }
  ],
  "meta": {
    "as_of": "2026-05-03T01:14:00Z",
    "slug": "eggs_cage_free_large_dozen",
    "name": "Eggs, Cage-Free, Large, Dozen",
    "description": "Average national price of one dozen large cage-free eggs.",
    "index_type": "single_sku",
    "method": "trimmed_mean",
    "source_methodology": "BLS-CPI inspired",
    "methodology_url": "https://api.mainmarket.com/methodology.md",
    "methodology_version": 2,
    "inception_period": "2025-06",
    "base_period": "2025-06",
    "base_value_usd": 4.92,
    "regions": ["national"],
    "constituents": [
      { "upc": "00071600051501", "name": "Vital Farms Pasture-Raised Large", "weight": 0.30 },
      { "upc": "00099482492700", "name": "Pete and Gerry's Organic Large", "weight": 0.25 }
    ],
    "chain_filter": null,
    "request_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
    "warning": null
  }
}

SnapshotRow fields (data[])

Name	Type	Description
`period`	string	Calendar month, YYYY-MM.
`value_usd`	number	Index value in USD (e.g. dollars per dozen, dollars per basket).
`value_indexed`	number \| null	Computed at query time from the index's frozen `base_value_usd`. Null while the index is in beta and no base has been chosen.
`n_observations`	integer	Distinct (store, product, day) rows used in the trimmed mean.
`n_stores, n_chains`	integer	Coverage breadth.
`coverage_score`	number	0.0–1.0 internal QA score for the period.
`publish_status`	string	One of `auto`, `beta`, `forced_publish`, `forced_hide`, `draft`.
`flagged_for_review, flag_reason`	mixed	Soft anomaly flag from the QA cron.
`revoked`	boolean	True when the snapshot was retracted after publication.
`methodology_version`	integer	Version of the formula used for this snapshot. Bumps invalidate older comparisons.
`computed_at`	timestamp	When the snapshot was written.

IndexMeta fields (meta)

Name	Type	Description
`as_of`	timestamp	Server time at request.
`slug, name, description`	string	Index identity.
`index_type`	string	One of `single_sku`, `multi_sku_same_format`, `basket_total_cost`.
`method`	string	Aggregation method label, e.g. trimmed_mean.
`source_methodology`	string \| null	Reference standard, e.g. 'BLS-CPI inspired'.
`methodology_url`	string	Stable URL to the full methodology doc.
`methodology_version`	integer	Current methodology version.
`inception_period, base_period`	string	Series-level period anchors (YYYY-MM).
`base_value_usd`	number \| null	USD value used as the index=100 anchor. Null while the index is in beta.
`regions`	string[]	Regions for which snapshots exist.
`constituents`	object[]	Per-product weights (UPC, name, weight). Used to reproduce the index locally.
`chain_filter`	object \| null	Optional chain inclusion/exclusion rules baked into this index.
`request_id`	uuid	Per-request id for support.
`warning`	string \| null	Soft warning, e.g. 'index is inactive: curation pending'.

ℹ

Beta values are unindexed

Notable behavior

Snapshots are written by a cron job. This route is read-only and never recomputes — a 200 OK with empty data means the slug exists but no snapshots match the requested window.

When the index exists but is inactive (curation pending), the response is 200 OK with empty data and meta.warning set.

The default 12-month window is calendar-month based. For deep history, set from explicitly.

Name

Type

Description

404

Not Found

Slug is not a known published index.

422

Unprocessable Entity

from or to not YYYY-MM, or region not in the supported list.

402

Payment Required

Paid route — no payment proof.