Event Ingestion API

PULSE event collection and ingestion API reference

Event Ingestion API

Ingest events from your applications into PULSE.

Endpoint

POST /collect

Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

{
  "site_id": "site_abc123",
  "event_type": "page_view",
  "timestamp": 1703001234567,
  "session_id": "session_xyz789",
  "user_id": "user_123",
  "url": "https://example.com/products",
  "referrer": "https://google.com",
  "country": "US",
  "device_type": "desktop"
}

Field Reference

Response

Success (202 Accepted):

{
  "success": true,
  "timestamp": 1703001234567
}

Error (400 Bad Request):

{
  "success": false,
  "error": "Missing required field: site_id",
  "timestamp": 1703001234567
}

Error (401 Unauthorized):

{
  "success": false,
  "error": "Invalid API key",
  "timestamp": 1703001234567
}

Error (429 Too Many Requests):

{
  "success": false,
  "error": "Rate limit exceeded",
  "timestamp": 1703001234567
}

Status Codes

Examples

cURL

curl -X POST https://api.example.com/collect \
  -H "Authorization: Bearer pulse_prod_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "site_abc123",
    "event_type": "page_view",
    "timestamp": '$(date +%s000)',
    "session_id": "session_123",
    "url": "https://example.com",
    "device_type": "desktop"
  }'

JavaScript

const event = {
  site_id: 'site_abc123',
  event_type: 'page_view',
  timestamp: Date.now(),
  session_id: generateSessionId(),
  url: window.location.href,
  referrer: document.referrer,
  device_type: 'desktop'
}

await fetch('https://api.example.com/collect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(event)
})

TypeScript SDK

import { PulseClient } from '@pulse/sdk'

const pulse = new PulseClient({
  siteId: 'site_abc123',
  apiKey: 'YOUR_API_KEY',
  endpoint: 'https://api.example.com'
})

await pulse.trackEvent({
  eventType: 'page_view',
  sessionId: 'session_123',
  url: '/products'
})

Event Types

Common event types:

page_view       -- User viewed a page
click           -- User clicked an element
form_submit     -- User submitted a form
user_signup     -- New user signed up
user_login      -- User logged in
user_logout     -- User logged out
purchase        -- User made a purchase
add_to_cart     -- Item added to cart
remove_from_cart -- Item removed from cart
error           -- Application error
custom          -- Custom application event

Validation Rules

• site_id: Max 64 characters, alphanumeric + underscore
• event_type: Max 64 characters, alphanumeric + underscore
• timestamp: Must be within last 30 days
• session_id: Max 64 characters
• user_id: Max 64 characters, optional
• url: Max 2048 characters
• device_type: One of: desktop, mobile, tablet

Rate Limiting

Events are rate limited per API key:

• Default: 10,000 events per minute
• Burst: Up to 100,000 events per minute (for 10 seconds)
• Limit Header: X-RateLimit-Remaining

Batch Ingestion

For better performance, batch multiple events:

curl -X POST https://api.example.com/collect/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event_type": "page_view", ... },
      { "event_type": "click", ... },
      { "event_type": "form_submit", ... }
    ]
  }'

Performance Tips

1. Batch Events — Group multiple events into one request
2. Use Sessions — Reuse same session_id for related events
3. Async Requests — Don’t wait for response
4. Buffer Events — Send every 5-10 seconds, not on every event
5. Compress — Use gzip for large batches

Troubleshooting

”Invalid API key”

• Check API key format: pulse_prod_xxxxx
• Verify Authorization header: Bearer YOUR_API_KEY
• Regenerate key if needed

”Missing required field”

• Verify all required fields present
• Check field names match exactly
• Ensure timestamp is number (milliseconds)

“Rate limit exceeded”

• Reduce event volume
• Batch events together
• Wait 60 seconds and retry

Events not appearing in queries

• Wait 5-10 seconds for processing
• Check site_id matches in queries
• Verify event timestamp is recent

Next Steps

• Analytics Queries — Query events
• First Event — Tutorial
• SDK Documentation — Client libraries