Query raw ingested records

1 min

GET

https://app.amberflo.io/usage/events

Retrieves raw events (records) sent to the ingest API for inspection and debugging. Provides direct access to meter data as it was originally submitted.

Important limitations:

Time range constraints: Maximum query span depends on event frequency and filters applied
Squashed events: For squashable meters, only the final squashed event is available, not individual records
High-frequency exclusions: Events from very high-frequency meters may not be available for query

Cost considerations: Query cost is determined by data scanned. Narrower time ranges and specific filters reduce costs significantly.

Typical use cases:

Debug ingestion issues and validate event data
Audit customer usage patterns and dimension values
Analyze raw event structure before aggregation
Troubleshoot missing or incorrect meter data

Query Parameters

meterApiNamestring
Description
Technical identifier of the meter to query events from. Must match existing meter in your account.
customerIdstring
Description
Unique identifier of the customer whose events to retrieve for filtering.
eventIdstring
Description
Specific event identifier to filter results by when querying individual events.
startTimeInSecondsinteger<int64>
Description
Unix timestamp marking the earliest time boundary for event retrieval (inclusive).
endTimeInSecondsinteger<int64>
Description
Unix timestamp marking the latest time boundary for event retrieval (exclusive).
limitinteger
Description
Maximum number of events to return in total across all pages.
pageSizeinteger
Description
Number of events to return per page for pagination control.
Default
100
isAscendingboolean
Description
Whether to sort events by timestamp in ascending order (true) or descending order (false).
nextPageTokenstring
Description
Pagination token returned from previous response to retrieve the next page of results.

Responses

200Successful request

events.MeterEventResponse.out
Description
Response structure containing raw ingested meter events in tabular format with pagination support
- columnsstring[]
  Description
  Array of column names defining the structure and order of data fields in each event row
- rowsarray[]
  Description
  Array of event records where each row contains string values corresponding to the columns array
- nextPageTokenstring
  Description
  Pagination token for retrieving the next page of results when more events are available
- queryevents.MeterEventQuery.out
  Description
  Original query parameters used to retrieve this set of meter event results
  - customerIdstring
    Description
    Unique identifier of the customer whose events to retrieve for filtering results
  - eventIdstring
    Description
    Specific event identifier to filter results by when querying individual events
  - meterApiNamestring
    Description
    Technical identifier of the meter to query events from, must match existing meter
  - timeRangecommon.TimeRange.out
    Description
    Time period boundaries specifying the window for event retrieval from ingestion records
    - startTimeInSecondsinteger<int64>required
      Description
      Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).
    - endTimeInSecondsinteger<int64>
      Description
      End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to "now".
  - dimensionsmap<string, string>
    Description
    Map of dimension names to values for filtering events by specific dimensional criteria
  - limitinteger<int32>
    Description
    Maximum number of events to return in total across all pages of results
  - isAscendingboolean
    Description
    Whether to sort events by timestamp in ascending order (true) or descending order (false)
  - pageSizeinteger<int32>
    Description
    Number of events to return per page for pagination control and response management
  - nextPageTokenstring
    Description
    Pagination token returned from previous response to retrieve the next page of results

curl

curl --request GET \
     --url 'https://app.amberflo.io/usage/events?pageSize=100' \
     --header 'accept: application/json'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://app.amberflo.io/usage/events?pageSize=100", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://app.amberflo.io/usage/events?pageSize=100")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://app.amberflo.io/usage/events?pageSize=100"

payload = {}
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

200

// Successful request
{
  "columns": [
    ""
  ],
  "rows": [
    [
      ""
    ]
  ],
  "nextPageToken": "",
  "query": {
    "customerId": "",
    "eventId": "",
    "meterApiName": "",
    "timeRange": {
      "startTimeInSeconds": "",
      "endTimeInSeconds": ""
    },
    "dimensions": "",
    "limit": "",
    "isAscending": false,
    "pageSize": "",
    "nextPageToken": ""
  }
}