Query Events

Retrieve and filter ingested usage events

GET /v1/events

Query Events

cURL

curl --request GET \
  --url https://api.example.com/v1/events

200

{
  "200": {},
  "400": {},
  "401": {},
  "500": {},
  "events": [
    {}
  ],
  "events[].id": "<string>",
  "events[].event_name": "<string>",
  "events[].external_customer_id": "<string>",
  "events[].customer_id": "<string>",
  "events[].timestamp": "<string>",
  "events[].properties": {},
  "events[].source": "<string>",
  "events[].environment_id": "<string>",
  "has_more": true,
  "iter_first_key": "<string>",
  "iter_last_key": "<string>",
  "total_count": 123,
  "offset": 123
}

Retrieve raw events that have been ingested into FlexPrice. Use this for debugging ingestion, building usage dashboards, or exporting event data for analysis.

Use Cases

• Debug event ingestion and verify data
• Build customer usage dashboards
• Export events for external analytics
• Audit event history for support tickets
• Verify property values and timestamps

Query Parameters

external_customer_id · string

Filter events by your customer identifier. Returns events for a specific customer.

event_name · string

Filter by event type (e.g., api_request, storage_usage).

event_id · string

Retrieve a specific event by its idempotency key.

start_time · string

ISO 8601 timestamp for the start of the time range. Defaults to 7 days ago if not provided.

Example: 2024-03-13T00:00:00Z

end_time · string

ISO 8601 timestamp for the end of the time range. Defaults to current time if not provided.

Example: 2024-03-20T23:59:59Z

source · string

Filter by event source (e.g., api, mobile_app, webhook).

property_filters · string

Filter events by properties. Format: key1:value1,value2;key2:value3

Examples:

• status:200,201 - Events where status is 200 or 201
• region:us-east-1;tier:premium - Events from us-east-1 AND premium tier

page_size · integer

Number of events to return per page. Default: 50, max: 50.

offset · integer

Number of events to skip for pagination. Default: 0.

sort · string

Field to sort by. Allowed values: timestamp, event_name. Default: timestamp.

Case-sensitive.

order · string

Sort order. Allowed values: asc, desc. Default: desc.

Case-sensitive.

count_total · boolean

If true, includes the total count of matching events in the response. Default: false.

Note: Counting can be slow for large datasets.

iter_first_key · string

For cursor-based pagination. Use the iter_first_key from the previous response to get the next page.

iter_last_key · string

For cursor-based pagination. Use the iter_last_key from the previous response.

Response

events · array

Array of event objects matching the query filters.

events[].id · string

Unique event identifier.

events[].event_name · string

Type of event (e.g., api_request).

events[].external_customer_id · string

Customer identifier from your system.

events[].customer_id · string

FlexPrice’s internal customer ID.

events[].timestamp · string

ISO 8601 timestamp when the event occurred.

events[].properties · object

Key-value pairs with event metadata.

events[].source · string

Event source identifier.

events[].environment_id · string

Environment where the event was ingested (e.g., production, staging).

has_more · boolean

Whether there are more events to fetch. Use for pagination.

iter_first_key · string

Cursor for the first event in the current page. Use for cursor-based pagination.

iter_last_key · string

Cursor for the last event in the current page. Use for cursor-based pagination.

total_count · integer

Total number of events matching the query. Only present if count_total=true.

offset · integer

Current offset for offset-based pagination.

Examples

cURL - Basic Query

curl -X GET "https://us.api.flexprice.io/v1/events?external_customer_id=customer_123&start_time=2024-03-13T00:00:00Z&end_time=2024-03-20T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination

FlexPrice supports two pagination methods:

Offset-Based Pagination

Simple but less efficient for large datasets:

// Page 1
const page1 = await client.events.query({
  externalCustomerId: 'customer_123',
  pageSize: 50,
  offset: 0
});

// Page 2
const page2 = await client.events.query({
  externalCustomerId: 'customer_123',
  pageSize: 50,
  offset: 50
});

Cursor-Based Pagination

More efficient for large datasets:

// Page 1
const page1 = await client.events.query({
  externalCustomerId: 'customer_123',
  pageSize: 50
});

// Page 2 - use cursor from page 1
if (page1.hasMore) {
  const page2 = await client.events.query({
    externalCustomerId: 'customer_123',
    pageSize: 50,
    iterFirstKey: page1.iterLastKey
  });
}

Property Filters

Filter events by properties using the property_filters parameter:

# Single filter with multiple values (OR)
property_filters=status:200,201,204

# Multiple filters (AND)
property_filters=status:200;region:us-east-1

# Complex filter
property_filters=tier:premium,enterprise;method:GET,POST;region:us-east-1

Response Example

{
  "events": [
    {
      "id": "evt_abc123",
      "event_name": "api_request",
      "external_customer_id": "customer_123",
      "customer_id": "cust_xyz789",
      "timestamp": "2024-03-20T15:04:05Z",
      "properties": {
        "endpoint": "/v1/users",
        "method": "GET",
        "status": 200,
        "response_time_ms": 45
      },
      "source": "api",
      "environment_id": "env_prod"
    },
    {
      "id": "evt_def456",
      "event_name": "api_request",
      "external_customer_id": "customer_123",
      "customer_id": "cust_xyz789",
      "timestamp": "2024-03-20T15:08:12Z",
      "properties": {
        "endpoint": "/v1/orders",
        "method": "POST",
        "status": 201,
        "response_time_ms": 120
      },
      "source": "api",
      "environment_id": "env_prod"
    }
  ],
  "has_more": true,
  "iter_first_key": "eyJ0aW1lc3RhbXAiOiIyMDI0LTAzLTIwVDE1OjA0OjA1WiIsImlkIjoiZXZ0X2FiYzEyMyJ9",
  "iter_last_key": "eyJ0aW1lc3RhbXAiOiIyMDI0LTAzLTIwVDE1OjA4OjEyWiIsImlkIjoiZXZ0X2RlZjQ1NiJ9",
  "offset": 0
}

Response Codes

200 · OK

Successfully retrieved events.

400 · Bad Request

Invalid query parameters. Check:

• start_time and end_time format
• sort field is valid (timestamp or event_name)
• order is valid (asc or desc)
• property_filters format

401 · Unauthorized

Missing or invalid API key.

500 · Server Error

Internal server error.

Best Practices

1. Use time ranges: Always specify start_time and end_time for predictable results and better performance.

2. Cursor pagination for large datasets: Use iter_first_key and iter_last_key instead of offset for better performance when fetching many pages.

3. Avoid count_total in production: Counting all matching events can be slow. Only use when necessary.

4. Filter early: Apply filters like event_name and external_customer_id to reduce the result set size.

5. Cache results: If displaying events in a dashboard, consider caching the response to avoid repeated API calls.

Related

• Ingest Event - Send a single event
• Batch Ingest Events - Send multiple events
• Usage Analytics - Aggregate and analyze event data