--- title: "Get holiday benchmark snapshot" method: POST path: "/v25-10-beta/analytics/event/snapshot" tags: ["Get Holiday Benchmark Data"] --- # Get holiday benchmark snapshot `POST /v25-10-beta/analytics/event/snapshot` ## Request - Base URL: `https://api.intelligems.io` - URL: `https://api.intelligems.io/v25-10-beta/analytics/event/snapshot` - Auth: API key in header `intelligems-access-token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieve a seasonal event benchmarking snapshot (Holiday Index and Brand Benchmark) for a shopping event such as BFCM or Labor Day. Returns a single KPI object summarizing the brand's performance across the requested window. To match the Intelligems dashboard's "Q4 to Date" tile, pass Oct 1 → Dec 31 of the event year. For time-indexed chart data across the event window, use `POST /analytics/event/timeseries`. ### Enumerations **`event`** — the seasonal event identifier: - `"BFCM"` — Black Friday / Cyber Monday - `"laborDay"` - `"memorialDay"` - `"presidentsDay"` **`metric`** — the KPI to return: - `"revenue"` — net revenue - `"orders"` — order count - `"priceLevels"` — average unit price ### Request | Field | Required | Type | Notes | | -------- | -------- | ------------------------ | ------------------------------------------------------------------------------------------ | | `event` | yes | event enum | See above. | | `metric` | yes | metric enum | See above. | | `year` | no | integer (2021–2026) | Which event year. Defaults to the most recently completed occurrence. | | `start` | **yes** | ISO 8601 datetime string | Beginning of the analysis window. For the dashboard Q4 view, pass Oct 1 of the event year. | | `end` | **yes** | ISO 8601 datetime string | End of the analysis window. For the dashboard Q4 view, pass Dec 31 of the event year. | ### Response ```json { "currency": "USD", "snapshot": { "periodToDateValue": 125000.5, "vsLastYear": 0.12, "avgDailyIndexPercent": 1.27, "currentIndexPercent": 1.23 } } ``` - `periodToDateValue` — brand actual value for the selected metric across the event window. Maps to the dashboard's "Q4 {Metric} to Date" tile. - `vsLastYear` — percent change vs. the same period in the prior event year (e.g. `0.12` = +12%). Maps to the ±% pill on the "Q4 to Date" tile. - `avgDailyIndexPercent` — the brand's average daily value as a percent of its own full-day baseline, across the window. Maps to the dashboard's "Avg Daily {Metric} (% of typical day)" tile. - `currentIndexPercent` — the industry-wide average daily index across the window (percent of full-day baseline, aggregated across the ~1,000-brand basket). Maps to the dashboard's "Index (% of typical day)" tile. All numeric fields are `number | null`. ### Rate limits Uses the same rate limit as the `/analytics/sitewide/*` endpoints. Aggregated, cacheable data — see the Rate Limiting Reference. **Rate Limit:** 10 requests per 30s window, refilling 5 tokens every 30s. ## Request body - object - `event` 'BFCM' | 'laborDay' | 'memorialDay' | 'presidentsDay', required: Seasonal event identifier. Supported values: "BFCM" (Black Friday / Cyber Monday), "laborDay", "memorialDay", "presidentsDay". - `metric` 'revenue' | 'orders' | 'priceLevels', required: Metric to return. Supported values: "revenue" (net revenue), "orders" (order count), "priceLevels" (average unit price). - `year` integer: Which year of the event to fetch (e.g. 2025 for BFCM 2025). Defaults to the most recently completed occurrence of the event. The prior-year comparison cohort is always year - 1. For hourly granularity, leave this unset or pass a year matching `end`'s year — passing a mismatched year + end will yield nonsensical results. - `start` string, date-time, required: Required. Start of analysis period as an ISO 8601 datetime string. Used to size the window before the event (days-before-holiday); does not influence which event year is fetched. For hourly granularity, ignored. To match the Intelligems dashboard's Q4 view, pass Oct 1 of the event year (58 days before BFCM). - `end` string, date-time, required: Required. End of analysis period as an ISO 8601 datetime string. Used to size the window after the event (days-after-holiday); does not influence which event year is fetched. For hourly granularity this is interpreted as "the day to analyze" and is expected to fall within `year`. To match the Intelligems dashboard's Q4 view, pass Dec 31 of the event year (33 days after BFCM). ## Response `200` OK - object - `currency` string, required: ISO 4217 currency code for monetary values (e.g. 'USD'). - `snapshot` object, required: KPI snapshot covering the brand's period-to-date event metrics. - `periodToDateValue` number, nullable, required: The brand's period-to-date actual value for the selected metric across the event window. - `vsLastYear` number, nullable, required: Percent change of the brand's period-to-date value vs the same period in the prior event year (e.g. 0.12 = +12%). - `avgDailyIndexPercent` number, nullable, required: The brand's average daily value as a percent of its own full-day baseline, across the event window. Maps to the dashboard's 'Avg Daily {Metric} (% of typical day)' tile. - `currentIndexPercent` number, nullable, required: The industry-wide average daily index across the event window (percent of full-day baseline, aggregated across the ~1,000-brand basket). Maps to the dashboard's 'Index (% of typical day)' tile. ## Other responses - `429`: Too Many Requests --- [API](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta.md) - [All operations](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/revisions/7b769b2f90b1?raw)