The endpoints are Ingest event and Bulk ingest events in the API Reference.
Usage event fields
event_name(required): matches the event name of the metered features that count the event, including case.external_customer_id(required): your ID for the customer, the same value as the customer’s External ID in Tirdad.event_id(recommended): a unique ID for this piece of usage. Generated when missing.timestamp(recommended): when the usage happened, as RFC 3339 with a timezone. Defaults to the time Tirdad receives the request.properties(optional): key-value pairs that features aggregate and filter on, as numbers or numeric strings.source(optional): free text naming the system that sent the event.
event_id and timestamp match, so a retried event without them counts twice. Usage event structure explains how to choose each value.
Sending a usage event with the API or SDKs
Authenticate with an API key in thex-api-key header, and send events from your servers only, never from browser or mobile code. Use the base URL https://api.tirdad.ai/v1.
timestamp as an RFC 3339 string and send it unchanged, and they take property values as strings only.
A single event returns 202 Accepted with its event ID:
202 means Tirdad accepted the event for processing. Metering runs asynchronously, so use the Event Debugger to confirm how an event was counted.
Sending usage events in bulk
POST /v1/events/bulk takes 1 to 1000 events in an events array, in a request body of up to 32 MiB. It returns 202 with {"message": "Events accepted for processing"} and no event IDs. Use it whenever you send more than a few events at a time: High-Volume Ingestion covers batching.
Usage event responses and errors
Errors other than
401 share one body, with the reason in message:
401 has a shorter body, such as {"error": "Invalid API key"}.
To build these rules into a sender, with a durable queue, backoff, and a dead letter queue, see Queuing and retrying usage events.
Send Usage Events
What to put in a usage event, and how to queue, retry, and log events.
Idempotency and Deduplication
How Tirdad recognizes a copy of an event, and how to make retries and heartbeats safe.
High-Volume Ingestion
Batch events with the bulk endpoint or the SDKs.
Event Debugger
See how each event was received and counted.