Summarize signals over time
Counts signals into period buckets. Use it to chart signal volume over time, split by signal name or by a signal-payload key such as team_id.
Signals count against their effective timestamp in UTC. This is the same basis billing uses, so these figures reconcile with an invoice.
The endpoint reads a pre-aggregated hourly rollup, not the raw signals. An hour is therefore the finest interval. One request may span at most 250 periods.
A grouped request keeps the 100 groups with the most signals. It sums the rest under the key "other". Each period total stays complete, but a group inside "other" loses its own figure. Read groups.truncated to learn how many groups lost it. Zero means every group kept its own figure.
Results are paged with limit and cursor. A page is never truncated in silence.
For a wide per-customer spreadsheet over arbitrary payload fields, use the batch export at /signals/summary/batch instead.
Request
- Base URL: https://api.agentpaid.io/api/v2
- URL: https://api.agentpaid.io/api/v2/signals/summary/
- Auth: HTTP bearer
Query parameters
Window start, inclusive. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
Window end, inclusive — a date-only value means through the end of that UTC day. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
Period size. Buckets align to UTC hours, calendar days, ISO weeks that start on Monday, or calendar months. An hour is the finest period available.
The first and last bucket report bounds clipped to your window.
A request may span at most 250 periods. That is about 10 days at hour, 8 months at day, and 20 years at month. A longer window returns 400 WINDOW_TOO_LARGE.
Narrow the summary to one customer. Accepts a Paid customer ID or, as a fallback, your external customer ID. Mutually exclusive with externalCustomerId. Omit both to summarize every customer.
Your external customer ID. Mutually exclusive with customerId.
Narrow the summary to these signal names. Repeat the parameter for more than one. Omit to count every signal.
Split each period into one series per group. signalName groups by the signal's name. dimension groups by a signal-payload key named in dimensionKey — signals per team, for example. Omit for one total per period.
A grouped request keeps the 100 groups with the most signals. It sums the rest under the key "other".
Each period total stays complete, but a group inside "other" loses its own figure. Read groups.truncated to learn how many groups lost it. To name every group, narrow the request with signalNames, customerId, or a shorter window.
The signal-payload key to group by. Required when groupBy is dimension; rejected otherwise. The key must be one your organization has declared for grouping — an undeclared key is refused rather than answered by a full scan. A signal whose payload lacks the key, or holds it empty, groups under an empty groupKey.
json returns the series as a JSON body. csv returns the same points as a text/csv table with a single header row.
A CSV cannot carry a cursor, so it is returned whole or refused. A result that does not fit one page returns 400 rather than a file that is quietly missing rows. Use json to page, or raise limit.
Group truncation never refuses a CSV. The "other" row is in the file, so nothing is hidden.
Maximum points to return in this page. The response is never silently truncated: when more points exist, hasMore is true and nextCursor is set.
Continue from a previous response's nextCursor. Every other parameter must be unchanged.
Response
200
Changes
No recorded changes to this operation across all 1 revision of this API.