POST /analytics/records
Updated Oct 1, 20263 minute read
List the rows a query matched
The rows behind an explore query, newest first unless sort says otherwise, each with a title, the dashboard page it opens, and one value per field. Takes the same body as POST /analytics/explore; filters, when and the window apply, while measure, groupBy and bucket are ignored.
Part of Analytics.
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
query | object | Yes | |
query.dataset | "conversations" | "ratings" | "signals" | "logs" | "knowledgeDocs" | "knowledgeSuggestions" | "toolRequests" | "toolRuns" | "customers" | "tasks" | "usageEvents" | "messages" | Yes | |
query.measure | object | No | |
query.measure.op | "count" | "distinct" | "sum" | "avg" | "median" | "p75" | "p90" | "p95" | "p99" | "min" | "max" | "percent" | Yes | count takes no field. distinct reads an id, string or enum field. percent takes no field but a where filter, and gives the share of matched rows passing it, 0 to 100. The rest read a number or duration field. |
query.measure.field | string | null | No | The field id the measure reads. |
query.measure.where | object | No | percent only: the condition to count the share of. Same shape as a filter. |
query.filters | object[] | No | Rows have to pass every filter, or any one with match: "any". Enum values are their ids, booleans are true or false, durations are milliseconds. isSet and isNotSet take no value; in and notIn take a list of up to 50. |
query.filters[].field | string | Yes | |
query.filters[].op | "is" | "isNot" | "gt" | "gte" | "lt" | "lte" | "contains" | "notContains" | "in" | "notIn" | "isSet" | "isNotSet" | Yes | |
query.filters[].value | string | number | boolean | string | number | boolean[] | No | |
query.match | "all" | "any" | No | all (the default) lets a row through when it passes every filter, any when it passes one. |
query.groupBy | string | null | No | A field id to split the rows into series by. Rows with nothing in the field land in __none. |
query.top | integer | No | How many groups keep their name. The rest fold into __other, which takes one of the places. |
query.order | "natural" | "largest" | "smallest" | No | natural keeps the field's own order (most rows first for free text). largest or smallest ranks the groups by the measure, and the ranking picks which keep their name. |
query.other | boolean | No | false leaves the groups past top off instead of folding them into __other. The total then covers only the groups returned. |
query.bucket | "day" | "week" | "month" | "hour" | "weekday" | No | The x axis. day, week and month cut the window up and need the range scope; hour and weekday fold every row onto one clock. |
query.when | object | No | |
query.when.field | string | No | Which of the dataset's time fields places a row. The dataset's first by default. |
query.when.scope | "range" | "all" | No | range for rows inside the window, all for every row on file. Default range. |
query.compare | boolean | No | Also measure the same number of days just before the window, returned as previous. Ignored with the all scope. |
days | integer | No | How far back the window reaches, counted from the UTC midnight before now. Default 30. |
from | integer | No | The window's start, unix ms, in place of counting back. |
limit | integer | No | How many rows to return. |
sort | object | No | The order of the rows. Rows with nothing in the field go last either way. |
sort.by | string | Yes | time for the moment the query placed each row at, or a field id. |
sort.direction | "desc" | "asc" | No | |
fields | string[] | No | Which field ids each row reads out, in this order. All of them by default. |
Responses
| Status | Description |
|---|---|
200 | The matched rows. |
400 | The request is malformed, and the message names the field. |
401 | The bearer token is missing, revoked, or expired. |
429 | Too many requests. Wait the seconds in Retry-After. Limits depend on the plan. See rate limits. |
200 body
| Field | Type | Required | Description |
|---|---|---|---|
ok | boolean | No | |
fields | string[] | No | |
rows | object[] | No | |
rows[].id | string | No | |
rows[].at | number | No | |
rows[].title | string | No | |
rows[].href | string | null | No | |
rows[].values | any[] | No | |
matched | integer | No | |
scanned | integer | No | |
capped | boolean | No |
Example request
curl -X POST https://api.median.sh/v1/analytics/records \
-H "Authorization: Bearer $BEARER_AUTH"