Pixel Data

Get started

Quickstart

From nothing to your first rated event, in about fifteen minutes.

4 min read

Before you start

You need an account and one ingest key. Ingest keys start pk_live_ and can only write events; they cannot read anything back. Keep the sk_live_ key for your own tooling and never put it in client-side code.

No account yet? The sandbox runs this whole flow on sample data with no signup and no card.

1. Send your first event

The fastest route is the agent, if your usage already exists as CDRs or logs on a machine you control.

curl -sL https://thepixeldata.com/install.sh | bash

If your usage happens inside your own application, post it instead. One endpoint accepts a single event or an array of up to 500.

POST /v1/events
curl -X POST https://api.thepixeldata.com/v1/events \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "5f0c1d84-6b1e-4a0e-9c7d-2e4b8f1a3c55",
    "event_type": "call",
    "timestamp": "2024-05-27T14:02:11Z",
    "account": "acct_alphacomms",
    "quantity": 372,
    "unit": "seconds",
    "properties": { "destination": "447700900123" }
  }'

The response tells you what happened to every item individually. Valid events are never rejected because an invalid one shared the batch.

{
  "accepted": 1,
  "dropped": 0,
  "rejected": 0,
  "results": [
    { "index": 0, "event_id": "5f0c1d84-6b1e-4a0e-9c7d-2e4b8f1a3c55", "status": "accepted" }
  ]
}

2. Upload a price plan

A plan is a CSV. Each line says: for this event type, when this property starts with this key, charge this rate, in these increments, with this minimum.

wholesale-2024-04.csv
match_key,rate,increment,minimum,event_type
44,0.000180,60,60,call
447,0.000420,1,30,call
4479,0.000870,1,30,call
447,0.032500,1,1,sms
Longest prefix wins. With the lines above, 447700900123 is rated at the 447 rate, and 447912345678 at the 4479 rate. This is intentional and is the behaviour telecom people expect.

3. Read it back

Three read endpoints cover most of what a dashboard needs: a summary, one event in full, and an account's statement for a month.

curl "https://api.thepixeldata.com/v1/usage/summary?from=2024-05-01&to=2024-06-01&group_by=account" \
  -H "Authorization: Bearer sk_live_…"