apps.patrol docs

Events API

POST /v1/events: send usage events from your app.

Send up to 100 usage events in one request. Valid events are stored even when others in the same request are rejected.

Request

POST https://www.apps-patrol.com/v1/events
Authorization: Bearer <ingest key>
Content-Type: application/json
{
  "events": [
    {
      "event_id": "0b7f0c1e-6d0a-4d6f-9a56-3f1c8f1f2a10",
      "shop": "example.myshopify.com",
      "name": "feature_used",
      "occurred_at": "2026-11-17T09:30:00Z",
      "properties": { "feature": "bulk_edit", "items": 42 }
    }
  ]
}

Event fields

FieldRequiredRules
event_idYesYour unique ID for the event, a string of at most 200 characters (a UUID works well). The same ID sent again for the same app is counted as a duplicate and not stored twice.
shopYesThe shop's *.myshopify.com domain. A shop that is not known yet is created.
nameYesAt most 100 characters from a-z, 0-9, _, ., : and -, for example feature_used or checkout.step:2.
occurred_atNoISO 8601 time, not more than 7 days in the past or 1 hour in the future. Defaults to the time of receipt.
propertiesNoA JSON object: at most 50 top-level keys, 3 levels of nesting and 8 KB.

Responses

StatusMeaning
202At least one event was stored or recognised as a duplicate. Check errors for rejected events.
422Nothing could be stored: every event was invalid (invalid_request, with errors), events is not an array (invalid_request), or there are more than 100 events (batch_too_large).
401unauthorized: missing, wrong or rotated ingest key.
413payload_too_large: the body is over 512 KB.
429rate_limited (too many requests this minute) or quota_exceeded (monthly allowance used).

202 body

{
  "accepted": 1,
  "duplicates": 0,
  "errors": [
    { "index": 1, "code": "missing_shop", "message": "shop is required" }
  ]
}
FieldMeaning
acceptedEvents newly stored.
duplicatesValid events whose event_id was already stored for this app, or repeated within the request.
errorsRejected events. index is the position in your events array; code is one of the per-event codes.

422 body when every event is invalid

{
  "error": { "code": "invalid_request", "message": "No event in the request could be stored", "docs": "https://www.apps-patrol.com/docs/errors#invalid_request" },
  "accepted": 0,
  "duplicates": 0,
  "errors": [
    { "index": 0, "code": "missing_event_id", "message": "event_id is required" }
  ]
}

Limits

LimitValue
Events per request100
Request body512 KB
Requests per ingest key600 per minute, shared by all /v1 endpoints
Events per organization per monthFree 10,000 · Solo 250,000 · Studio 2,000,000 · Agency 10,000,000

Rate limit headers

Every response carries the state of the per-minute limit:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1794907260

X-RateLimit-Reset is the Unix time when the window ends. A 429 rate_limited response also has Retry-After in seconds.

Monthly quota

Only newly stored events count; duplicates and rejected events do not. The month is a calendar month in UTC. When the allowance is used, requests are answered with 429 quota_exceeded and nothing is stored until the next month or a plan change. The Events page shows the current usage, ping returns it, and the “Event quota” alert warns you at 80% and 100%.

Behaviour to rely on

  • Idempotent: retry a failed request with the same event_ids. Nothing is stored or counted twice.
  • Order does not matter: events are placed by occurred_at.
  • Partial success: one bad event does not reject the batch.

Test mode

Add the header X-Apps-Patrol-Test: true to validate a request without storing anything. The response is the one you would get, plus "test": true. Test requests do not count toward the monthly quota; they do count toward the rate limit.

Example

curl -X POST https://www.apps-patrol.com/v1/events \
  -H "Authorization: Bearer $APPS_PATROL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[
        {"event_id":"evt-1001","shop":"example.myshopify.com","name":"app_opened"},
        {"event_id":"evt-1002","shop":"example.myshopify.com","name":"feature_used","properties":{"feature":"bulk_edit"}}
      ]}'
{"accepted":2,"duplicates":0,"errors":[]}