Search

API Reference

V1

Usage

Search events

v1.usage.search(UsageSearchParams**kwargs) -> idstrcustomer_idstrevent_typestrtimestampdatetimetransaction_idstris_duplicateboolmatched_billable_metricslistmatched_customerUsageSearchResponseItemMatchedCustomerprocessed_atdatetimepropertiesDict[str, object]UsageSearchResponse

post/v1/events/search

For a set of events, look up matched billable metrics and customers by transaction id. This endpoint looks at transactions that occurred in the last 34 days, and is intended for sampling-based testing workflows. It is heavily rate limited.

Parameters

transaction_idslist

List[str]

The transaction IDs of the events to retrieve

Returns

UsageSearchResponsetype

List[UsageSearchResponseItem]

Hide ParametersShow Parameters

idstr

customer_idstr

The ID of the customer in the ingest event body

event_typestr

timestampdatetime

formatdate-time

transaction_idstr

is_duplicatebool

optional

matched_billable_metricslist

optional

Optional[List[UsageSearchResponseItemMatchedBillableMetric]]

Hide ParametersShow Parameters

idstr

formatuuid

namestr

aggregatestr

optional

(DEPRECATED) use aggregation_type instead

aggregate_keyslist

optional

Optional[List[str]]

(DEPRECATED) use aggregation_key instead

aggregation_keystr

optional

A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is 'count'.

aggregation_typeliteral

optional

Optional[Literal["COUNT", "LATEST", "MAX", 2 more]]

Specifies the type of aggregation performed on matching events.

Hide ParametersShow Parameters

"COUNT"

"LATEST"

"MAX"

"SUM"

"UNIQUE"

archived_atdatetime

optional

RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived.

formatdate-time

custom_fieldsDict[str, str]

optional

Optional[Dict[str, str]]

event_type_filterEventTypeFilter

optional

An optional filtering rule to match the 'event_type' property of an event.

filterDict[str, object]

optional

Optional[Dict[str, object]]

(DEPRECATED) use property_filters & event_type_filter instead

group_bylist

optional

Optional[List[str]]

(DEPRECATED) use group_keys instead

group_keyslist

optional

Optional[List[List[str]]]

Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets.

property_filterslist

optional

Optional[List[namestrexistsboolin_valueslistnot_in_valueslistPropertyFilter]]

A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric.

Hide ParametersShow Parameters

namestr

The name of the event property.

existsbool

optional

Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional.

in_valueslist

optional

Optional[List[str]]

Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present.

not_in_valueslist

optional

Optional[List[str]]

Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present.

sqlstr

optional

The SQL query associated with the billable metric

matched_customeridstrnamestrUsageSearchResponseItemMatchedCustomer

optional

The customer the event was matched to if a match was found

Hide ParametersShow Parameters

idstr

optional

formatuuid

namestr

optional

processed_atdatetime

optional

formatdate-time

propertiesDict[str, object]

optional

Optional[Dict[str, object]]

HTTPTypeScriptPythonGoRubyTerraform

from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
response = client.v1.usage.search(
    transaction_ids=["2021-01-01T00:00:00Z_cluster42"],
)
print(response)

200 Example

[
  {
    "id": "id",
    "customer_id": "customer_id",
    "event_type": "event_type",
    "timestamp": "2019-12-27T18:11:19.117Z",
    "transaction_id": "transaction_id",
    "is_duplicate": true,
    "matched_billable_metrics": [
      {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "name": "name",
        "aggregate": "aggregate",
        "aggregate_keys": [
          "string"
        ],
        "aggregation_key": "aggregation_key",
        "aggregation_type": "COUNT",
        "archived_at": "2019-12-27T18:11:19.117Z",
        "custom_fields": {
          "foo": "string"
        },
        "event_type_filter": {
          "in_values": [
            "string"
          ],
          "not_in_values": [
            "string"
          ]
        },
        "filter": {
          "foo": "bar"
        },
        "group_by": [
          "string"
        ],
        "group_keys": [
          [
            "string"
          ]
        ],
        "property_filters": [
          {
            "name": "name",
            "exists": true,
            "in_values": [
              "string"
            ],
            "not_in_values": [
              "string"
            ]
          }
        ],
        "sql": "sql"
      }
    ],
    "matched_customer": {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "name": "name"
    },
    "processed_at": "2019-12-27T18:11:19.117Z",
    "properties": {
      "foo": "bar"
    }
  }
]