Vayu Docs

Vayu processes events in batches. If some events in a batch are invalid, only those are discarded — valid events are still ingested.

Event Structure

Each event requires four fields:

Field	Type	Description
`name`	string	Event label (e.g. `api_call`, `storage_used`)
`timestamp`	ISO 8601 datetime	When the event occurred (UTC)
`customerAlias`	string	Identifies the customer (external ID or alias)
`ref`	string	Unique reference for idempotency
`data`	object (optional)	Arbitrary key-value metadata

Batch Limits

Minimum events: 1
Maximum events: 1,000
Maximum size of a single event: 1 MB — a larger event returns 413 Request Entity Too Large

Example

import { Vayu } from 'vayu-ts';

const vayu = new Vayu(process.env.VAYU_API_KEY);

const result = await vayu.events.send([
  {
    name: 'api_call',
    timestamp: new Date(),
    customerAlias: 'customer-123',
    ref: 'evt_abc123',
    data: { endpoint: '/users', method: 'GET' },
  },
]);

console.log('Valid:', result.validEvents.length);
console.log('Invalid:', result.invalidEvents.length);

from vayu_sdk import Vayu
from datetime import datetime, timezone
import os

vayu = Vayu(api_key=os.environ["VAYU_API_KEY"])
vayu.login()

result = vayu.events.send(events=[
    {
        "name": "api_call",
        "timestamp": datetime.now(timezone.utc),
        "customerAlias": "customer-123",
        "ref": "evt_abc123",
        "data": {"endpoint": "/users", "method": "GET"},
    },
])

print("Valid:", len(result.valid_events))
print("Invalid:", len(result.invalid_events))

import vayu "github.com/vayucode/vayu-sdks/go"

v := vayu.NewVayu(os.Getenv("VAYU_API_KEY"))

result, err := v.Events.SendEvents([]vayu.Event{
    {
        Name:          "api_call",
        Timestamp:     time.Now().UTC(),
        CustomerAlias: "customer-123",
        Ref:           "evt_abc123",
        Data: map[string]interface{}{
            "endpoint": "/users",
            "method":   "GET",
        },
    },
})

fmt.Println("Valid:", len(result.ValidEvents))
fmt.Println("Invalid:", len(result.InvalidEvents))

curl -X POST "https://connect.withvayu.com/events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $VAYU_CLIENT_ID" \
  -d '{
    "events": [
      {
        "name": "api_call",
        "timestamp": "2026-04-14T12:00:00Z",
        "customerAlias": "customer-123",
        "ref": "evt_abc123",
        "data": { "endpoint": "/users", "method": "GET" }
      }
    ]
  }'

Response Structure

The response includes two arrays:

validEvents — events that Vayu accepted and queued for processing. Each one carries an ackId, a per-event acknowledgment ID that you can keep as proof the event reached Vayu.
invalidEvents — events that failed validation, each with the original event and an error message

{
  "validEvents": [
    {
      "name": "api_call",
      "timestamp": "2026-04-14T12:00:00Z",
      "customerAlias": "customer-123",
      "ref": "evt_abc123",
      "data": { "endpoint": "/users", "method": "GET" },
      "ackId": "01J5A3B7K9QRSTUV2WXYZ4DEFG"
    }
  ],
  "invalidEvents": []
}

A 200 response means Vayu accepted the events and queued them. Processing continues asynchronously, so accepted events become queryable through the API and visible in the UI a short time after the response. Usage and measurements update after metering processes the events.

Invalid events do not cause the entire request to fail. They are returned in the invalidEvents array while valid events are still processed.

Sending events

Event Structure

Batch Limits

Example

Response Structure

Availability

On this page