Skip to main content
You can retrieve usage events from Quivly using two APIs:
  1. Fetch a single event by its event_id
  2. List events with flexible filters and pagination

​
Fetch an Event by event_id

Retrieve a specific event using its unique event_id:
  • Returns the event object if found.
  • Returns a 404 if the event does not exist.

​
Example: GET an Event

Sample Request
curl -X GET "https://api.quivly.com/v1/events/abc-123" \
  -H "Authorization: Bearer YOUR_API_KEY"
Sample Response
{
  "event_id": "abc-123",
  "customer_id": "pied-piper",
  "event_code": "api_call",
  "event_type": "credit",
  "created_at": "2025-03-25T12:00:00Z",
  "event_properties": {
    "tokens": "300",
    "status_code": 200,
    "region": "us-west-1",
    "response_time_ms": 120
  }
}

​
List Events with Filters

Retrieve a list of events using a POST request with a JSON body. This method supports complex filters, large queries, and avoids URL length limitations.

​
Supported Filters

You can filter events using the following fields in the POST body:
  • customer_id: Filter by customer
  • event_code: Filter by metric code
  • event_type: credit or debit
  • created_at_from: Start of time range (RFC 3339/ISO 8601, UTC)
  • created_at_to: End of time range (RFC 3339/ISO 8601, UTC)
  • event_property_filters: Object of event_properties to filter by (e.g., { "region": "us-west-1" })

​
Pagination

  • limit: Number of events to return (default: 50, max: 100)
  • offset: Number of events to skip (for pagination)

​
Example: POST Search for Events

Sample Request
curl -X POST "https://api.quivly.com/v1/events/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "pied-piper",
    "created_at_from": "2025-03-01T00:00:00Z",
    "created_at_to": "2025-03-31T23:59:59Z",
    "event_property_filters": { "region": "us-west-1" },
    "limit": 50
  }'
Sample Response
{
  "events": [
    {
      "event_id": "abc-123",
      "customer_id": "pied-piper",
      "event_code": "api_call",
      "event_type": "credit",
      "created_at": "2025-03-25T12:00:00Z",
      "event_properties": {
        "tokens": "300",
        "status_code": 200,
        "region": "us-west-1",
        "response_time_ms": 120
      }
    },
    {
      "event_id": "def-456",
      "customer_id": "pied-piper",
      "event_code": "api_call",
      "event_type": "credit",
      "created_at": "2025-03-26T09:15:00Z",
      "event_properties": {
        "tokens": "150",
        "status_code": 200,
        "region": "us-west-1",
        "response_time_ms": 110
      }
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}
If you do not specify a limit, the API will return up to 50 events by default. The maximum allowed per request is 100 events.
Use POST request for all event queries, including complex filters and large result sets.