--- title: Query raw ingested records slug: reference/query-raw-ingested-records docTags: createdAt: 2025-01-21T18:39:14.860Z --- { "id": "-UJlR54ofl6N8KzCeOLkY", "type": "api-oas-v2", "data": { "method": "GET", "url": "https://app.amberflo.io/usage/events", "servers": [ { "url": "https://app.amberflo.io/usage/events" } ], "name": "Query raw ingested records", "description": "

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

\n

Important limitations:

\n\n

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

\n

Typical use cases:

\n", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [ { "kind": "optional", "name": "meterApiName", "type": "string", "description": "Technical identifier of the meter to query events from. Must match existing meter in your account." }, { "kind": "optional", "name": "customerId", "type": "string", "description": "Unique identifier of the customer whose events to retrieve for filtering." }, { "kind": "optional", "name": "eventId", "type": "string", "description": "Specific event identifier to filter results by when querying individual events." }, { "kind": "optional", "name": "startTimeInSeconds", "type": "integer", "description": "

Unix timestamp marking the earliest time boundary for event retrieval (inclusive).

" }, { "kind": "optional", "name": "endTimeInSeconds", "type": "integer", "description": "

Unix timestamp marking the latest time boundary for event retrieval (exclusive).

" }, { "kind": "optional", "name": "limit", "type": "integer", "description": "Maximum number of events to return in total across all pages." }, { "kind": "optional", "name": "pageSize", "type": "integer", "description": "Number of events to return per page for pagination control.", "default": 100 }, { "kind": "optional", "name": "isAscending", "type": "boolean", "description": "

Whether to sort events by timestamp in ascending order (true) or descending order (false).

" }, { "kind": "optional", "name": "nextPageToken", "type": "string", "description": "Pagination token returned from previous response to retrieve the next page of results." } ], "bodyDataParameters": [], "formDataParameters": [], "oAuthParameters": [ { "id": "apiKey", "name": "X-API-KEY", "kind": "optional", "type": "apiKey", "in": "header" } ] }, "responses": [ { "statusCode": "200", "description": "Successful request", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "Response structure containing raw ingested meter events in tabular format with pagination support", "customType": "events.MeterEventResponse.out", "schema": [ { "name": "columns", "kind": "optional", "type": "array", "description": "Array of column names defining the structure and order of data fields in each event row", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "rows", "kind": "optional", "type": "array", "description": "Array of event records where each row contains string values corresponding to the columns array", "example": "", "itemType": "array", "customType": "array[]", "itemExample": "", "itemDefault": "" }, { "name": "nextPageToken", "kind": "optional", "type": "string", "description": "Pagination token for retrieving the next page of results when more events are available", "example": "" }, { "name": "query", "kind": "optional", "type": "object", "description": "Original query parameters used to retrieve this set of meter event results", "modelRef": "#/components/schemas/events.MeterEventQuery.out", "customType": "events.MeterEventQuery.out", "schema": [ { "name": "customerId", "kind": "optional", "type": "string", "description": "Unique identifier of the customer whose events to retrieve for filtering results", "example": "" }, { "name": "eventId", "kind": "optional", "type": "string", "description": "Specific event identifier to filter results by when querying individual events", "example": "" }, { "name": "meterApiName", "kind": "optional", "type": "string", "description": "Technical identifier of the meter to query events from, must match existing meter", "example": "" }, { "name": "timeRange", "kind": "optional", "type": "object", "description": "Time period boundaries specifying the window for event retrieval from ingestion records", "modelRef": "#/components/schemas/common.TimeRange.out", "customType": "common.TimeRange.out", "schema": [ { "name": "startTimeInSeconds", "kind": "required", "type": "integer", "description": "Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).", "example": 0 }, { "name": "endTimeInSeconds", "kind": "optional", "type": "integer", "description": "End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to \"now\".", "example": 0 } ] }, { "name": "dimensions", "kind": "optional", "type": "map", "description": "Map of dimension names to values for filtering events by specific dimensional criteria", "example": "", "customType": "map", "schema": [] }, { "name": "limit", "kind": "optional", "type": "integer", "description": "Maximum number of events to return in total across all pages of results", "example": 0 }, { "name": "isAscending", "kind": "optional", "type": "boolean", "description": "Whether to sort events by timestamp in ascending order (true) or descending order (false)", "example": "" }, { "name": "pageSize", "kind": "optional", "type": "integer", "description": "Number of events to return per page for pagination control and response management", "example": 0 }, { "name": "nextPageToken", "kind": "optional", "type": "string", "description": "Pagination token returned from previous response to retrieve the next page of results", "example": "" } ] } ], "modelRef": "#/components/schemas/events.MeterEventResponse.out", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "ephTSsR9BNy4arLqU4_GN", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url 'https://app.amberflo.io/usage/events?pageSize=100' \\\n --header 'accept: application/json'" }, { "id": "YEsqbWCttQLCpH4APTnIC", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/usage/events?pageSize=100\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "AkrVpukz86FPXbMCL-X_y", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/usage/events?pageSize=100\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "_N9A3ciBnGS5sZzkt8FRF", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/usage/events?pageSize=100\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "ephTSsR9BNy4arLqU4_GN" }, "results": { "languages": [ { "id": "WLfYG7vZxdroE6q4lGBMT", "language": "200", "code": "// Successful request\n{\n \"columns\": [\n \"\"\n ],\n \"rows\": [\n [\n \"\"\n ]\n ],\n \"nextPageToken\": \"\",\n \"query\": {\n \"customerId\": \"\",\n \"eventId\": \"\",\n \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": \"\",\n \"endTimeInSeconds\": \"\"\n },\n \"dimensions\": \"\",\n \"limit\": \"\",\n \"isAscending\": false,\n \"pageSize\": \"\",\n \"nextPageToken\": \"\"\n }\n}" } ], "selectedLanguageId": "WLfYG7vZxdroE6q4lGBMT" } }, "children": [ { "text": "", "id": "0EbPoRX-CLs5gUIqQkQjG" } ] }