Send analytics events
POST /api/v1/analytics/events records that an image was seen, clicked, or acted on.
The script tag sends these for you. Call it directly only if you render images yourself and still want the dashboard numbers.
curl -X POST https://pixloom.dev/api/v1/analytics/events \
-H "Authorization: Bearer pk_live_..." \
-H "Content-Type: application/json" \
-d '{
"events": [
{ "imageId": "b71e...", "eventType": "impression" },
{ "imageId": "b71e...", "eventType": "click", "metadata": { "page": "/pricing" } }
]
}'
# 202 { "accepted": 2 }Either kind of key works. Batch up to a hundred events per request.
Events
| Field | Type | Notes |
|---|---|---|
eventType | enum | Required. The list is below. |
imageId | uuid | Optional, but an event without one tells you very little. |
metadata | object | Optional. Anything you want to keep, such as the page or placement. |
eventType is one of impression, click, generate, cache_hit, pin, reject, style_applied, heart, flag, view. In practice you send impression and click; the rest are recorded by our own pipeline as images are generated and managed, and are listed here only so nothing surprises you in an export.
Why it always says yes
A 202 means we received your events. It does not promise they were stored. If our analytics store is having a bad day we still answer 202 and drop the batch.
That is deliberate. This endpoint sits on the path of a page that a real person is looking at, and a slow or broken analytics write must never be the reason an image does not appear. Numbers are worth less than the page.
accepted is simply how many events were in your request.
Rate limits
This endpoint has its own budget, separate from generation. Telemetry from a busy page can never eat into the generations you are paying for. The per-minute ceiling is the same as your plan's, listed in errors and limits.
Responses
| Status | Body |
|---|---|
202 | { "accepted": 2 } |
400 | { "error": "Invalid request", "details": { ... } }. An empty events array lands here. |
401 | Missing or invalid key. |
403 | Account not approved. |
429 | { "error": "Rate limit exceeded" }. Drop the batch and move on. |