{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-PublicAPI/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Usage Report Endpoint","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"usage-report-endpoint","__idx":0},"children":["Usage Report Endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/usagereport"]}]}," endpoint is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["self-service monitoring tool"]},". It lets you, the API consumer, see how many calls your application has made against the Dentrix Ascend Public API ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["so far this month"]},", broken down by endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," a billing report, an entitlement check, or a per-organization audit. Its sole purpose is to let you watch your own month-to-date traffic so you can stay ahead of your monthly allotment."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tldr","__idx":1},"children":["TL;DR"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The endpoint returns the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["month-to-date request count for your apiConsumer"]},", broken down by endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Counts are aggregated ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per apiConsumer (your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["developer_app"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},")"]}," — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," per organization, and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," per ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}," + organization combination."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Organization-ID"]}," header is required"]},", but only because every Public API call requires one for authentication. It does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," filter or scope the numbers you get back."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The endpoint ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["does not return data on the first day of the month"]}," — there is nothing to report yet."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-this-endpoint-is-for","__idx":2},"children":["What this endpoint is for"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/usagereport"]}," to answer questions like:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"How many API calls has my integration made this month?\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Which endpoints am I hitting most?\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Am I trending toward my monthly call allotment?\""]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is intended as a lightweight monitoring tool you can poll from your own dashboards or operational tooling. It is the same data we use internally to track consumer-level traffic against the proxy."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-this-endpoint-is-not","__idx":3},"children":["What this endpoint is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is a common point of confusion, so to be explicit — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/usagereport"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per-organization"]}," usage report. The numbers returned are not scoped to the organization you pass in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Organization-ID"]}," header."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["billing"]}," report or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["invoice"]},". Per-location billing is calculated separately. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/publicapi/location-filtering"},"children":["Location-Based API Billing"]}," for how billing usage is computed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["rate-limit"]}," status endpoint. It does not tell you how close you are to a per-minute or per-second throttle — only your aggregated month-to-date counts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["historical"]}," report. The valid date range is constrained to the current month (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#filters"},"children":["Filters"]}," below)."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-aggregation-works","__idx":4},"children":["How aggregation works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Usage is counted ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}]},", where the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}," is your registered application credential (internally ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["developer_app"]},", surfaced to your code as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_name"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}," is linked to multiple organizations, every call made by that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}," — regardless of which ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Organization-ID"]}," was on the request — contributes to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same"]}," total. There is no per-org breakdown in the response, and changing the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Organization-ID"]}," header on your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/usagereport"]}," request will ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," change the numbers you receive."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"why-the-organization-id-header-is-still-required","__idx":5},"children":["Why the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Organization-ID"]}," header is still required"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Organization-ID"]}," is required on ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["every"]}," Public API request as part of standard authentication. The Public API verifies that your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," is authorized for the organization in the header before it will service the request. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/publicapi/api-consumer-guide"},"children":["API Consumer Guide — Authentication"]}," for the broader header requirements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/usagereport"]}," specifically:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The header is checked for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["security/authorization"]}," only."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," used as a filter on the returned data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Any organization your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}," is authorized for is a valid value here, and you will get the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same"]}," month-to-date counts back regardless of which one you use."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request","__idx":6},"children":["Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/v1/usagereport\nOrganization-ID: <any organization your apiConsumer is authorized for>\nAuthorization: Bearer <access_token>\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"filters","__idx":7},"children":["Filters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All filters are optional and use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["=="]}," (equals) operator, consistent with other Public API filter syntax."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Filter"},"children":["Filter"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["First day of the current month"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Cannot be earlier than the first day of the current month. Cannot equal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDate"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The current date"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Cannot be later than the current date. Cannot equal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDate"]},". Cannot be earlier than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDate"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(all endpoints)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Must be a known endpoint name with no version prefix or special characters (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["appointments"]},", not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/appointments"]},"). If omitted, the response is broken down by endpoint."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dates use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," format and are interpreted as the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["start of day in UTC"]}," (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-03-01"]}," is equivalent to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-03-01T00:00:00Z"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-requests","__idx":8},"children":["Example requests"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Default — month-to-date totals for every endpoint:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/v1/usagereport\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Narrow to a specific endpoint:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/v1/usagereport?filter=endpoint==\"appointments\"\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Narrow to a date range within the current month:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/v1/usagereport?filter=startDate==\"2026-06-01\",endDate==\"2026-06-15\"\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Combine all three filters:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/v1/usagereport?filter=startDate==\"2026-06-01\",endDate==\"2026-06-15\",endpoint==\"appointments\"\n"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response","__idx":9},"children":["Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"statusCode\": 200,\n  \"data\": {\n    \"usagePerEndpoint\": [\n      { \"endpoint\": \"appointments\",  \"requestCount\": 12345 },\n      { \"endpoint\": \"transactions\",  \"requestCount\":  4321 },\n      { \"endpoint\": \"patients\",      \"requestCount\":  9876 }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usagePerEndpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["One entry per endpoint your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}," has called in the requested time range."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usagePerEndpoint[].endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The endpoint name (no version prefix)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usagePerEndpoint[].requestCount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Total request count for that endpoint across ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["all"]}," organizations your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}," is linked to, within the requested time range."]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Endpoints your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}," has not called in the requested time range are simply omitted from the array. An empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usagePerEndpoint"]}," array means no traffic was recorded."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"constraints-and-edge-cases","__idx":10},"children":["Constraints and edge cases"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["First day of the month"]}," — The endpoint will not return statistics if called on the first day of the month. There is no aggregated data yet for the current period."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Date range must be within the current month"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDate"]}," cannot be earlier than the first day of the current month, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDate"]}," cannot be later than today. To look at a prior month's totals, you must capture and store the response yourself before the month rolls over."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDate"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDate"]}," cannot be equal"]}," — Use a range of at least one day."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stats are aggregated, not real-time"]}," — Counts come from analytics and may lag the most recent traffic by a short period. Treat the numbers as month-to-date observations, not as a live counter you can use for fine-grained throttling decisions."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-misunderstandings","__idx":11},"children":["Common misunderstandings"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Misunderstanding"},"children":["Misunderstanding"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Reality"},"children":["Reality"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"The numbers I see are for the org in my ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Organization-ID"]}," header.\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No — the header is for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["authentication only"]},". The numbers are aggregated for your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiConsumer"]}]}," across every organization it is linked to."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"I should call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/usagereport"]}," per org to see per-org usage.\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The endpoint does not break out usage by organization. Every call you make to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/usagereport"]}," returns the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same"]}," apiConsumer-level totals, regardless of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Organization-ID"]}," header."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"This endpoint tells me what I will be billed.\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No — billing (especially per-location billing) is computed independently. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/publicapi/location-filtering"},"children":["Location-Based API Billing"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"Why am I getting an error on the 1st of the month?\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The endpoint intentionally returns no statistics on the first day of the month — there is nothing to aggregate yet. Resume calls on the 2nd."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"I want to see last month's totals.\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The endpoint only supports the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["current"]}," month. Capture and persist the response near the end of each month if you need a historical record."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":12},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Poll on a sensible cadence."]}," Hourly or every few hours is typically plenty for trend monitoring. There is no benefit to polling every minute — the underlying analytics are not real-time and you would just be burning your own allotment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Persist your own snapshots"]}," if you need historical (prior-month) totals. The endpoint will not give them to you after the month rolls over."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpoint"]}," filter"]}," when you only care about traffic to a specific endpoint — it makes the response easier to consume in dashboards."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not use it as a rate-limit gate."]}," It is a monitoring aid, not an authoritative real-time counter. For rate-limit behavior, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/publicapi/api-consumer-guide"},"children":["API Consumer Guide — Rate Limiting"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Combine with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/publicapi/location-filtering"},"children":["Location-Based API Billing"]}]}," when planning your integration's overall API footprint — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usagereport"]}," tells you ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["how many"]}," calls you've made, while location billing explains ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["what those calls cost"]},"."]}]}]},"headings":[{"value":"Usage Report Endpoint","id":"usage-report-endpoint","depth":1},{"value":"TL;DR","id":"tldr","depth":2},{"value":"What this endpoint is for","id":"what-this-endpoint-is-for","depth":2},{"value":"What this endpoint is not","id":"what-this-endpoint-is-not","depth":2},{"value":"How aggregation works","id":"how-aggregation-works","depth":2},{"value":"Why the Organization-ID header is still required","id":"why-the-organization-id-header-is-still-required","depth":3},{"value":"Request","id":"request","depth":2},{"value":"Filters","id":"filters","depth":3},{"value":"Example requests","id":"example-requests","depth":3},{"value":"Response","id":"response","depth":2},{"value":"Constraints and edge cases","id":"constraints-and-edge-cases","depth":2},{"value":"Common misunderstandings","id":"common-misunderstandings","depth":2},{"value":"Best practices","id":"best-practices","depth":2}],"frontmatter":{"title":"Usage Report Endpoint","toc":true,"category":"monitoring","description":"How the /v1/usagereport endpoint works, what it actually measures, and how to use it to monitor your month-to-date API call volume.","seo":{"title":"Usage Report Endpoint"}},"lastModified":"2026-06-02T22:47:33.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/publicapi/usage-report","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}