Skip to content

Send a batch of events

POST
/v1/ingest
curl --request POST \
--url https://stats.example.com/v1/ingest \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "v": 1, "mode": "privacy", "sdk": { "name": "example", "version": "example" }, "app": { "id": "example", "env": "example", "release": "example" }, "source": { "shards": [ 1 ], "cluster": 1, "instance": "example" }, "sentAt": "2026-04-15T12:00:00Z", "events": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "ts": 1, "weight": 1, "type": "interaction", "kind": "chat_input", "command": "example", "group": "example", "sub": "example", "commandId": "example", "commandScope": "global", "options": [], "optionValues": { "additionalProperty": "example" }, "customId": "example", "componentType": 1, "sourceCommand": "example", "context": 0, "install": "guild", "guild": "example", "channelType": 1, "locale": "example", "guildLocale": "example", "memberTier": "admin", "user": "example", "actor": { "userId": "example", "username": "example", "avatar": "example" }, "premium": true, "outcome": "ok", "errorCode": 1, "errorClass": "example", "ackMs": 1, "responseType": 1, "deferred": true, "ephemeral": true, "handlerMs": 1, "shard": 1 } ] }'

Gzipped JSON (Content-Encoding: gzip), at most 500 events, 1 MB compressed and 5 MB decompressed. Invalid events are rejected one by one; duplicates (retries) are counted, not stored twice.

Media typeapplication/json
Shardlens batch (wire format v1)
object
v
required
number
Allowed value: 1
mode
required
string
Allowed values: privacy audit
sdk
required
object
name
required
string
<= 64 characters /^[^\u0000]*$/
version
required
string
<= 32 characters /^[^\u0000]*$/
app
required
object
id
required
string
/^(?:\d{17,18}|[1-8]\d{18}|9[01]\d{17})$/
env
required
string
<= 32 characters /^[^\u0000]*$/
release
string
<= 64 characters /^[^\u0000]*$/
source
required
object
shards
required
Array<integer>
cluster
integer
>= -9007199254740991 <= 9007199254740991
instance
required
string
<= 128 characters /^[^\u0000]*$/
sentAt
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))$/
events
required
Array
>= 1 items <= 500 items
One of:
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$/
ts
required
integer
> 0 <= 9007199254740991
weight
number
default: 1 > 0 <= 10000
type
required
string
Allowed value: interaction
kind
required
string
Allowed values: chat_input user_context message_context primary_entry_point button select modal_submit autocomplete
command
string
<= 32 characters /^[^\u0000]*$/
group
string
<= 32 characters /^[^\u0000]*$/
sub
string
<= 32 characters /^[^\u0000]*$/
commandId
string
/^(?:\d{17,18}|[1-8]\d{18}|9[01]\d{17})$/
commandScope
string
Allowed values: global guild
options
Array<string>
default: <= 25 items
optionValues
object
key
additional properties
Any of:
string
<= 100 characters /^[^\u0000]*$/
customId
string
<= 100 characters /^[^\u0000]*$/
componentType
integer
>= -9007199254740991 <= 9007199254740991
sourceCommand
string
<= 32 characters /^[^\u0000]*$/
context
Any of:
number
0
install
string
Allowed values: guild user both
guild
string
/^(?:\d{17,18}|[1-8]\d{18}|9[01]\d{17})$/
channelType
integer
>= -9007199254740991 <= 9007199254740991
locale
required
string
<= 10 characters /^[^\u0000]*$/
guildLocale
string
<= 10 characters /^[^\u0000]*$/
memberTier
string
Allowed values: admin manager member dm
user
required
string
/^h1:(\d{4}-\d{2}(-\d{2})?|\d{4}-W\d{2}):[0-9a-f]{32}$/
actor
object
userId
required
string
/^(?:\d{17,18}|[1-8]\d{18}|9[01]\d{17})$/
username
string
<= 64 characters /^[^\u0000]*$/
avatar
string
/^(a_)?[0-9a-f]{32}$/
premium
required
boolean
outcome
required
string
Allowed values: ok error timeout no_response
errorCode
integer
>= -9007199254740991 <= 9007199254740991
errorClass
string
<= 64 characters /^[^\u0000]*$/
ackMs
integer
<= 9007199254740991
responseType
integer
>= -9007199254740991 <= 9007199254740991
deferred
boolean
ephemeral
boolean
handlerMs
integer
<= 9007199254740991
shard
integer
<= 9007199254740991

Accepted

Media typeapplication/json
object
accepted
required
integer
<= 9007199254740991
duplicates
required
integer
<= 9007199254740991
rejected
Array<object>
default:
object
index
required
integer
<= 9007199254740991
reason
required
string
<= 64 characters

Example

{
"rejected": []
}

Invalid batch envelope, or audit data sent to a privacy-mode app

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"
}
]
}

The batch is for another application

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"
}
]
}

Body too large

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"
}
]
}

Rate limited; retry after the Retry-After header

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"
}
]
}

Busy; retry after the Retry-After header

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"
}
]
}