Send Usage Events

Ingest usage events via API, CSV, or data integrations

Send usage events to Alguna to power usage-based billing. Events are aggregated according to your billable metrics and automatically appear on customer invoices.

---

Event Structure

Events are the basic unit of billable usage. Each event represents a single action a customer may be billed for.

Fields

Field	Type	Required	Description
unique_id	string	Yes	Idempotency key, max 72 characters
event_name	string	Yes	Event name (matches your metric)
account	string	Yes	Customer ID (cust_…) or alias
timestamp	RFC 3339	No	When the event occurred. Defaults to now
properties	object	No	Flat key/value event data for filtering and aggregation

Example Event

{
  "unique_id": "evt_abc123xyz789",
  "event_name": "api_request",
  "account": "cust_01H1VECT",
  "timestamp": "2026-04-01T10:30:00Z",
  "properties": {
    "endpoint": "/api/v1/users",
    "method": "GET",
    "response_time_ms": 45,
    "bytes_transferred": 2048,
    "status_code": 200
  }
}

---

Send via API

The recommended method for real-time event ingestion. POST /events always takes an events array — a single event is an array of one.

Single Event

await alguna.events.ingest({
  events: [
    {
      unique_id: crypto.randomUUID(),
      event_name: 'api_request',
      account: 'cust_01H1VECT',
      timestamp: new Date().toISOString(),
      properties: {
        endpoint: '/api/v1/users',
        method: 'GET',
        bytes_transferred: 2048,
      },
    },
  ],
});

Batch Events

Send multiple events in a single request (recommended for high volume). A request accepts up to 100 events:

await alguna.events.ingest({
  events: [
    {
      unique_id: 'evt_001',
      event_name: 'api_request',
      account: 'cust_01H1VECT',
      timestamp: '2026-04-01T10:30:00Z',
      properties: { endpoint: '/api/v1/users', bytes: 1024 },
    },
    {
      unique_id: 'evt_002',
      event_name: 'api_request',
      account: 'cust_01H1VECT',
      timestamp: '2026-04-01T10:30:01Z',
      properties: { endpoint: '/api/v1/orders', bytes: 2048 },
    },
    {
      unique_id: 'evt_003',
      event_name: 'api_request',
      account: 'cust_01H1WQ2R',
      timestamp: '2026-04-01T10:30:02Z',
      properties: { endpoint: '/api/v1/products', bytes: 512 },
    },
  ],
});

cURL Example

curl -X POST https://api.alguna.io/events \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "unique_id": "evt_abc123",
        "event_name": "api_request",
        "account": "cust_01H1VECT",
        "timestamp": "2026-04-01T10:30:00Z",
        "properties": {
          "endpoint": "/api/v1/users",
          "method": "GET"
        }
      }
    ]
  }'

Response

The response echoes the unique_id of every event that was accepted and every one that was not:

{
  "ingested": ["evt_abc123"],
  "failed": []
}

---

Send via CSV

Upload a CSV in the dashboard for batch ingestion or historical data.

CSV Format

Three columns are required — timestamp, account and event_name. Add one column per event property, each prefixed with prop_:

timestamp,account,event_name,prop_endpoint,prop_bytes
2026-04-01T10:00:00Z,cust_01H1VECT,api_request,/api/users,1024
2026-04-01T10:01:00Z,cust_01H1VECT,api_request,/api/orders,2048
2026-04-01T10:02:00Z,cust_01H1WQ2R,api_request,/api/products,512

Upload via Dashboard

1. Navigate to Events in the dashboard
2. Click Upload via File
3. Download the provided CSV template
4. Add your events and export the file as CSV
5. Upload the file

Uploaded files and their processing results are listed on the Uploaded tab of the Events page.

CSV Best Practices

• Use the downloaded template so the required headers match exactly
• Use RFC 3339 timestamps
• Prefix every property column with prop_
• Leave no blank cells — rows with empty values are rejected

---

Send via Data Sources

Connect an external data source and let Alguna pull billable events in on a schedule.

Source	Description
BigQuery	Google BigQuery dataset
ClickHouse	ClickHouse table or view

---

Customer Identification

Using the Alguna Customer ID

{
  account: 'cust_01H1VECT' // Alguna customer ID
}

Using Aliases

Use your own customer identifiers by adding them as aliases on the customer:

await alguna.customers.update('cust_01H1VECT', {
  aliases: ['customer_123', 'cus_abc123', '001ABC'],
});

Any alias then resolves to that customer:

{ account: 'customer_123' }  // Your system's ID
{ account: 'cus_abc123' }    // Stripe ID
{ account: '001ABC' }        // Salesforce ID

---

Idempotency & Deduplication

Unique ID Requirements

The unique_id field is an idempotency key: an event that repeats a unique_id already ingested for the same customer, event name and timestamp is counted once, not twice. It is capped at 72 characters — hash longer natural keys before sending.

// Good: UUID
{ unique_id: crypto.randomUUID() }

// Good: a collision-resistant natural key, hashed to stay under 72 characters
{ unique_id: hash(`request:${requestId}`) }

// Bad: same ID for different events (they will be deduplicated)
{ unique_id: 'event' }

---

Timestamps

Requirements

• Must be RFC 3339 (ISO 8601) format
• Optional — omit it and Alguna stamps the event with the time it was received
• Use the time the usage actually occurred: the timestamp decides which billing period the event falls into

Examples

// Valid formats
'2026-04-01T10:30:00Z'           // UTC
'2026-04-01T10:30:00+05:30'      // With timezone
'2026-04-01T10:30:00.123Z'       // With milliseconds

// Problematic
'2026-04-01'                      // Missing time
'04/01/2026 10:30 AM'            // Wrong format
'2027-04-01T10:30:00Z'           // Future date — falls outside the current billing period

Backdating Events

Ingest historical events in batches of up to 100:

await alguna.events.ingest({
  events: historicalEvents.map(e => ({
    unique_id: `historical_${e.id}`,
    event_name: 'api_request',
    account: e.customerId,
    timestamp: e.occurredAt, // Historical timestamp
    properties: e.data,
  })),
});

---

Properties

Properties carry event data used for filtering and aggregation. properties is a flat key/value map of up to 50 keys.

Common Property Patterns

// API usage
{
  properties: {
    endpoint: '/api/v1/users',
    method: 'GET',
    status_code: 200,
    response_time_ms: 45,
    bytes_transferred: 2048,
  }
}

// Compute usage
{
  properties: {
    instance_type: 'gpu.large',
    duration_seconds: 3600,
    region: 'us-east-1',
  }
}

// Storage usage
{
  properties: {
    storage_class: 'standard',
    bytes_stored: 1073741824,
    region: 'eu-west-1',
  }
}

// AI/ML usage
{
  properties: {
    model: 'gpt-4',
    input_tokens: 1500,
    output_tokens: 500,
    latency_ms: 2300,
  }
}

Property Types

Type	Example	Use Case
String	"us-east-1"	Filtering, grouping
Number	1024	Aggregation (sum, max)
Boolean	true	Filtering

Nesting is not supported. Flatten structured data into prefixed keys — request_method, response_bytes — so metric filters and aggregations can reach it.

---

Error Handling

The API returns errors as a status and a detail message. See the API overview for the full status-code list.

{
  "status": 422,
  "detail": "events array must not exceed 100 items"
}

The SDK turns those into typed errors — ValidationError, AuthenticationError, NotFoundError, RateLimitError — all extending AlgunaError. See error handling in the SDK reference.

import { ValidationError } from '@alguna/sdk';

try {
  await alguna.events.ingest({ events });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid event:', error.fields);
  }
}

Partial Failures

A 200 response does not mean every event landed. Check the failed array — it lists the unique_id of each event that could not be ingested, so you can correct and resend just those.

Retry Strategy

async function ingestWithRetry(events, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await alguna.events.ingest({ events });
    } catch (error) {
      if (error.statusCode >= 500 && attempt < maxRetries) {
        // Server error, retry with backoff
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
      throw error;
    }
  }
}

Retries are safe: the same unique_id is deduplicated rather than double-counted.

---

High-Volume Ingestion

Batch Recommendations

A request carries at most 100 events, so scale by sending more requests rather than bigger ones.

Volume	Batch size	Frequency
< 1,000/min	1–100	Real-time
1,000–10,000/min	100	Every 1–5 seconds
> 10,000/min	100	Continuous batching, requests in parallel

For backfills and continuous high-volume feeds, prefer a data source integration over the API.

---

Best Practices

Batch Events

Send events in batches of up to 100 for better performance.

Unique IDs

Generate truly unique IDs, under 72 characters, to prevent duplicates.

Accurate Timestamps

Use the actual event time, not ingestion time.

Rich Properties

Include the flat properties needed for filtering and aggregation.

---

Troubleshooting

Events Not Appearing

1. Check event timestamp is within the billing period
2. Verify account is a known customer ID or a configured alias
3. Confirm event_name matches your metric
4. Review the failed array in the API response

Usage Shows Zero

1. Verify events are being sent successfully
2. Check metric configuration and filters
3. Confirm event properties match metric requirements

Duplicate Charges

1. Ensure unique_id is truly unique per event
2. Check for duplicate event sends in your code
3. Review event logs for repeated ingestion

---

Next Steps

Define Metrics

Configure billable metrics.

Metrics Reference

Complete metrics configuration guide.