# 08 Get Holiday Benchmark Data ## POST /v25-10-beta/analytics/event/snapshot > ```json {"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta (dev)","version":"v25-10-beta"},"tags":[{"name":"08-get-holiday-benchmark-data"}],"servers":[{"url":"https://api.intelligems.io","description":"Dev"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/analytics/event/snapshot":{"post":{"tags":["08-get-holiday-benchmark-data"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["BFCM","laborDay","memorialDay","presidentsDay"],"description":"Seasonal event identifier. Supported values: \"BFCM\" (Black Friday / Cyber Monday), \"laborDay\", \"memorialDay\", \"presidentsDay\"."},"metric":{"type":"string","enum":["revenue","orders","priceLevels"],"description":"Metric to return. Supported values: \"revenue\" (net revenue), \"orders\" (order count), \"priceLevels\" (average unit price)."},"year":{"description":"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.","type":"integer","minimum":2021,"maximum":2026},"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"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":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"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)."}},"required":["event","metric","start","end"]}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."}},"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 currency code for monetary values (e.g. 'USD')."},"snapshot":{"type":"object","properties":{"periodToDateValue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The brand's period-to-date actual value for the selected metric across the event window."},"vsLastYear":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"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":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"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":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"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."}},"required":["periodToDateValue","vsLastYear","avgDailyIndexPercent","currentIndexPercent"],"additionalProperties":false,"description":"KPI snapshot covering the brand's period-to-date event metrics."}},"required":["currency","snapshot"],"additionalProperties":false}}}}}}}}} ``` ## POST /v25-10-beta/analytics/event/timeseries > ```json {"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta (dev)","version":"v25-10-beta"},"tags":[{"name":"08-get-holiday-benchmark-data"}],"servers":[{"url":"https://api.intelligems.io","description":"Dev"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/analytics/event/timeseries":{"post":{"tags":["08-get-holiday-benchmark-data"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["BFCM","laborDay","memorialDay","presidentsDay"],"description":"Seasonal event identifier. Supported values: \"BFCM\" (Black Friday / Cyber Monday), \"laborDay\", \"memorialDay\", \"presidentsDay\"."},"metric":{"type":"string","enum":["revenue","orders","priceLevels"],"description":"Metric to return. Supported values: \"revenue\" (net revenue), \"orders\" (order count), \"priceLevels\" (average unit price)."},"xAxis":{"type":"string","enum":["actualDate","daysFromEvent"],"description":"How each datapoint's `dt` is labeled. \"actualDate\" returns an ISO 8601 datetime; \"daysFromEvent\" returns a signed integer string (e.g. \"-3\", \"0\", \"2\") relative to the event day."},"granularity":{"type":"string","enum":["hourly","daily"],"description":"\"hourly\" returns one datapoint per hour for the event day (uses the holiday_benchmarking_single_day dataset). \"daily\" returns one datapoint per day across a range spanning the event (uses holiday_benchmarking_multiple_days)."},"mode":{"type":"string","enum":["index","brand","brandWithIndex"],"description":"\"index\" returns industry-wide index values only (currentYearIndex, priorYearIndex). \"brand\" returns the caller's brand actuals vs baseline (currentValue, baselineValue, priorYearValue). \"brandWithIndex\" returns brand actuals plus the brand's own index (brandIndex) and industry index overlays."},"year":{"description":"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.","type":"integer","minimum":2021,"maximum":2026},"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"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":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"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)."}},"required":["event","metric","xAxis","granularity","mode","start","end"]}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."}},"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 currency code for monetary values (e.g. 'USD')."},"data":{"type":"array","items":{"type":"object","properties":{"dt":{"type":"string","description":"Datapoint label — an ISO 8601 datetime (when xAxis='actualDate') or a signed day offset as a string (when xAxis='daysFromEvent')."},"dayOffset":{"description":"Signed integer event-offset for this datapoint (0 = event day, negative = before, positive = after). Present on daily-granularity responses; omitted on hourly responses.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currentValue":{"description":"Brand actual value for the selected metric during the current event year. Populated when mode is 'brand' or 'brandWithIndex'.","anyOf":[{"type":"number"},{"type":"null"}]},"baselineValue":{"description":"Brand typical-day baseline value for the selected metric. Populated when mode is 'brand' or 'brandWithIndex'.","anyOf":[{"type":"number"},{"type":"null"}]},"priorYearValue":{"description":"Brand actual value for the selected metric during the prior event year. Populated when mode is 'brand' or 'brandWithIndex'.","anyOf":[{"type":"number"},{"type":"null"}]},"currentYearIndex":{"description":"Industry-wide index value (percent of full-day baseline) for the current event year. Populated when mode is 'index' or 'brandWithIndex'.","anyOf":[{"type":"number"},{"type":"null"}]},"priorYearIndex":{"description":"Industry-wide index value for the prior event year. Populated when mode is 'index' or 'brandWithIndex'.","anyOf":[{"type":"number"},{"type":"null"}]},"brandIndex":{"description":"The brand's own value expressed as a percent of its full-day baseline. Populated when mode is 'brandWithIndex'.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["dt"],"additionalProperties":false},"description":"Array of datapoints indexed by `dt`. Each entry may populate a subset of value fields depending on the requested `mode`."}},"required":["currency","data"],"additionalProperties":false}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.intelligems.io/developer-resources/external-api-dev/08-get-holiday-benchmark-data.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.