--- title: "QueryIngestionTimeseries returns event ingestion counts bucketed by time, suitable for plotting trend charts in a single call." method: POST path: "/v1.1/analytics/event_ingestion/timeseries" tags: ["ControlService"] --- # QueryIngestionTimeseries returns event ingestion counts bucketed by time, suitable for plotting trend charts in a single call. `POST /v1.1/analytics/event_ingestion/timeseries` Returns one series per dimension tuple, each with an ordered, zero-filled array of {timestamp, success, errors} buckets at the requested interval. See the interval field for granularity and retention rules. Requires the read:analytics scope. Subject to the shared analytics rate limit (10 requests per minute). ## Request body - ProtobufControlpbV1QueryIngestionTimeseriesRequest - `dimensions` string[], nullable — Providing dimensions will split the data into one series per unique combination of dimension values. The allowed dimensions are - write_key (pipeline) - event_name - reason With no dimensions, a single series of whole-cluster totals is returned. - `end` string, date-time, nullable — End of the query range, exclusive. RFC 3339 UTC timestamp. Must be after start. - `filters` union — Filters restrict which events are counted before bucketing. Filters and dimensions are independent: filtering by write_key does not require grouping by write_key. - object, nullable - ProtobufStreamingpbV1IngestionStatFilters - `eventNames` string[], nullable — Normalized event names, e.g. order_completed. - `writeKeys` string[], nullable — Pipeline write keys. - `interval` string — Bucket width for the returned buckets, expressed as a duration string: a number with a unit suffix "s", "m", or "h" (e.g. "30m", "1h", "24h"). Units may be combined, e.g. "1h30m". The response echoes the effective interval in normalized form (e.g. "300s" becomes "5m"). The interval must be a whole multiple of 1 minute. Which multiples are allowed depends on how far back the range starts, because finer-grained data is retained for less time. Divisibility — not size — decides the tier: - Multiples of 24h (1 day), e.g. "24h", "168h": allowed for any range within the 13-month retention period. - Multiples of 1h that are not multiples of 1 day, e.g. "1h", "2h", "12h": the range must start on or after 00:00 UTC six days before the current UTC day (roughly the last 7 days). - Every other multiple of 1 minute, e.g. "1m", "5m", "30m": the range must start within the last 48 hours. Note "90m" lands in this tier — it is larger than an hour but not a whole multiple of one. In addition, the range divided by the interval must yield at most 400 buckets. Violations return INVALID_ARGUMENT (HTTP 400) naming the violated rule and the finest interval that fits the range. Buckets are aligned to the Unix epoch in UTC: hour-multiple intervals start on the hour, day-multiple intervals at 00:00 UTC (note: a 7-day interval therefore starts buckets on Thursdays). For intervals finer than 1 hour, buckets starting within the last 2 minutes are omitted because their data is still arriving and would under-report; data_through in the response marks where the returned data stops. Counts are attributed to buckets by the time the platform recorded the stat, which can lag the event itself by up to ~65 seconds — at minute granularity a burst of traffic may appear one bucket later than it occurred. If unset, the server selects the finest interval permitted by the rules above and echoes it in the response. - `options` string[], nullable — Optional behaviors. INGESTION_ANALYTICS_OPTION_ACTIVE_PIPELINES: automatically filter to currently deployed pipeline write keys (mutually exclusive with write key filters). - `start` string, date-time, nullable — Start of the query range, inclusive. RFC 3339 UTC timestamp. ## Response `200` OK - ProtobufControlpbV1QueryIngestionTimeseriesResponse - `dataThrough` string, date-time, nullable — Exclusive upper bound of the returned buckets. Equals end, except when an interval finer than 1 hour omits still-arriving trailing buckets — then data_through marks where the returned data stops. Totals cover only the returned buckets; compare data_through with end to detect truncation. - `end` string, date-time, nullable — Echo of the requested range end. - `interval` string — The effective bucket width as a normalized duration string (e.g. "5m", "1h", "24h"): the requested interval, or the server-selected one when the request omitted it. - `series` union[], nullable — One series per dimension tuple. Every series contains one bucket per interval from start through data_through, zero-filled — buckets with no events are present with zero counts, so the series can be plotted directly without gap handling. - union - object, nullable - ProtobufStreamingpbV1IngestionStatSeries - `buckets` union[], nullable — Buckets in ascending time order, one per interval in the queried range, zero-filled. - union - object, nullable - ProtobufStreamingpbV1IngestionStatBucket - … - `dimensions` object, nullable — The dimension values identifying this series, keyed by dimension name (e.g. {"write_key": "...", "event_name": "..."}). Empty when the request had no dimensions. - `start` string, date-time, nullable — Echo of the requested range start. - `totalDelivered` string — Total number of events successfully ingested across the entire range and all series. - `totalErrors` string — Total number of events that failed ingestion and will not be processed, across the entire range and all series. Unexpected data loss. ## Other responses - `4XX` — Something is wrong with your request such as missing or invalid data. Correct your request and try again. - `5XX` — Internal server error. Try again later or reach out to MetaRouter support. --- [API](https://skmtc.net/metarouter/apis/control-api.md) · [All operations](https://skmtc.net/metarouter/apis/control-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/metarouter/control-api/versions/5afc05bfaaa2/schema)