Skip to content

Run a typed query

POST
/v1/query
curl --request POST \
--url https://stats.example.com/v1/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "kind": "series", "metric": "interactions", "name": "example", "range": { "from": "2026-04-15T12:00:00Z", "to": "2026-04-15T12:00:00Z" }, "interval": "minute", "groupBy": "command", "stat": "count", "filters": [], "timezone": "UTC", "limit": 10 }'

Every query kind maps to a fixed SQL template with bound parameters. There is no per-user grouping.

Media typeapplication/json
One of:
object
kind
required
string
Allowed values: series
metric
required
string
Allowed values: interactions interactions.autocomplete components modals.submitted modals.shown interactions.errors rest.calls rest.invalid rest.ratelimits guild.joins guild.leaves guild.unavailable custom
name
string
/^[a-z][a-z0-9_]{0,63}$/
range
required
object
from
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
to
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
interval
required
string
Allowed values: minute hour day week month
groupBy
string
Allowed values: command sub kind outcome context install guild locale tier custom_id source option error_class method route status scope detected
stat
string
default: count
Allowed values: count sum avg p50 p95 p99
filters
Array<object>
default: <= 10 items
object
field
required
string
Allowed values: command sub kind outcome context install guild locale tier custom_id source option error_class method route status scope detected
op
string
default: eq
Allowed values: eq in
value
required
Any of:
string
<= 200 characters
timezone
string
default: UTC <= 64 characters
limit
integer
default: 10 >= 1 <= 20

Query result (shape depends on kind)

Invalid query

Media typeapplication/json
object
error
required
string
<= 64 characters
message
string
<= 500 characters
rejected
Array<object>
object
index
required
integer
<= 9007199254740991
reason
required
string
<= 64 characters

Example generated

{
"error": "example",
"message": "example",
"rejected": [
{
"index": 1,
"reason": "example"
}
]
}

Missing or wrong credentials

Media typeapplication/json
object
error
required
string
<= 64 characters
message
string
<= 500 characters
rejected
Array<object>
object
index
required
integer
<= 9007199254740991
reason
required
string
<= 64 characters

Example generated

{
"error": "example",
"message": "example",
"rejected": [
{
"index": 1,
"reason": "example"
}
]
}