Get Insight Experience Over Time - Birdeye Developer Portal

get_insight_experience_over_time

Description

Returns the experience score trend over a date range, broken into intervals (day, week, month, quarter, or year), alongside the sentiment, reputation, listing, and call scores that feed into the overall experience score for each interval. Use this to answer “how has our experience score trended?” questions. The response contains:

groupByType — the time interval used to group results (e.g. "month")
dataPoints (array) — one entry per interval, each with:
- startDate, endDate — interval boundaries
- label, shortLabel — display labels for the interval (e.g. "May 2026" / "May '26")
- experienceScore — overall experience score for the interval
- sentiment.score, reputation.score, listing.score, call.score — component scores for the interval

businessNumbers is required for this tool. Call get_child_locations first to get valid businessNumber values. If the user has not specified which locations to include, present the available locations and ask them to choose before calling this tool.

Parameters

Required

Parameter	Type	Description
`startDate`	string (`MM/DD/YYYY`)	Start of the date range
`endDate`	string (`MM/DD/YYYY`)	End of the date range
`businessNumbers`	list[integer]	`businessNumber` values of the locations to include (max 100) — from `get_child_locations`

Optional

Parameter	Type	Description
`groupBy`	string	Time interval to group by — one of `"day"`, `"week"`, `"month"`, `"quarter"`, `"year"`
`reviewSources`	list[string]	Filter by review sources (e.g. `["Google", "Facebook"]`)
`ratings`	list[string]	Filter by rating values (e.g. `["1", "2", "3", "4", "5"]`)

Example Usage

How has my experience score trended month over month this year?

Show my experience score by quarter for the NYC location.

Has our experience score improved or declined over the last 6 months?