Quickstart: Query Your First Events

What You'll Learn

By the end of this guide, you'll:

Have an API key for the Events API
Query events from your pixel
Understand the response format

Time required: 10 minutes

Prerequisites

Before starting, you need:

A Delivr.ai account (sign up here)
A pixel installed on your website (setup guide)
Some traffic to your site (at least a few page views)

Step 1: Get Your API Key

If you already have an API key, skip to Step 2.

1.1 Login to get a JWT token

curl --request POST \
  --url https://apiv2.delivr.ai/auth/v1/login \
  --header 'content-type: application/json' \
  --data '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD"
  }'

Response:

{
  "user_id": "221708ad-7dad-...",
  "organization_id": "66fede73-6811-...",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Copy the token value.

1.2 Create an API client

curl --request POST \
  --url https://apiv2.delivr.ai/client/v1 \
  --header 'authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Quickstart Client"
  }'

Response:

{
  "client_id": "69ee5598-b550-...",
  "api_key": "dlvr_f0997864bf3db3bc99d68864e72...",
  "api_secret": "b0b1b44a54c8fe77bda7634e9e86da00...",
  "created_at": "2025-01-01 10:00:00"
}

Save your api_key now - it cannot be retrieved later. This is your X-API-Key for all Events API calls.

Step 2: Find Your Pixel ID

You need your pixel ID to query events. Find it in:

Dashboard: Go to Settings > Pixels > Copy the pixel ID
Or from your pixel script: Look at the URL in your installed script:
```
<script src="https://cdn.delivr.ai/pixels/YOUR_PIXEL_ID/p.js"></script>
```

Step 3: Query Your Events

Now let's fetch the last hour of events from your pixel.

Calculate timestamps

The Events API uses millisecond timestamps. Here's how to get the last hour:

# Current time in milliseconds
END_MS=$(date +%s)000

# One hour ago in milliseconds
START_MS=$(($(date +%s) - 3600))000

echo "Start: $START_MS"
echo "End: $END_MS"

Make the request

curl --request GET \
  --url "https://apiv2.delivr.ai/api/v1/events?pixel_id=YOUR_PIXEL_ID&start_ms=START_MS&end_ms=END_MS&limit=10" \
  --header "X-API-Key: YOUR_API_KEY"

Example with real values:

curl --request GET \
  --url "https://apiv2.delivr.ai/api/v1/events?pixel_id=8a755c42-b2b1-4a59-a7d7-762076123456&start_ms=1704063600000&end_ms=1704067200000&limit=10" \
  --header "X-API-Key: dlvr_f0997864bf3db3bc99d68864e72..."

Step 4: Understand the Response

{
  "data": [
    {
      "event_id": "evt_abc123...",
      "event_type": "pageview",
      "event_time": "2025-01-01T10:30:00Z",
      "event_url": "https://yoursite.com/pricing",
      "resolved": true,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Acme Corp",
      "job_title": "VP of Marketing"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 10
}

Key fields

Field	Description
`resolved`	`true` if we identified the visitor
`email`	Visitor's email (if resolved)
`first_name`, `last_name`	Visitor's name (if resolved)
`company_name`	Visitor's company (if resolved)
`event_type`	Type of event (pageview, click, etc.)
`event_url`	Page where the event occurred

Step 5: Filter for Resolved Events Only

To get only identified visitors, add a filter:

curl --request GET \
  --url "https://apiv2.delivr.ai/api/v1/events?pixel_id=YOUR_PIXEL_ID&start_ms=START_MS&end_ms=END_MS&filter=resolved:eq:true&limit=10" \
  --header "X-API-Key: YOUR_API_KEY"

Common Issues

Problem	Solution
Empty results	Check your pixel is installed and has received traffic
401 Unauthorized	Verify your API key is correct
400 Bad Request	Check timestamp format (must be milliseconds)
Time window error	Ensure `end_ms - start_ms <= 25 hours`

What's Next?

Now that you can query events, explore more:

Count events - Get aggregate counts without fetching all data
Get schema - See all available fields
Filter & project - Advanced querying with filters and field selection
Export to S3 - Bulk export for data warehouses

Quick Reference

# Events endpoint
GET https://apiv2.delivr.ai/api/v1/events

# Required parameters
?pixel_id=UUID           # Your pixel ID
&start_ms=1704063600000  # Start timestamp (milliseconds)
&end_ms=1704067200000    # End timestamp (milliseconds)

# Optional parameters
&limit=100               # Max rows (default: 100, max: 1000)
&offset=0                # Skip rows for pagination
&filter=resolved:eq:true # Filter expression
&select=email,company    # Fields to return

# Required header
X-API-Key: your_api_key