Skip to main content

Documentation Index

Fetch the complete documentation index at: https://guide.withvayu.com/llms.txt

Use this file to discover all available pages before exploring further.

The dry run endpoint processes your events exactly as the live ingestion pipeline would — validating, matching customers, and evaluating meters — but does not store any data. Use it to verify your event schema, check customer matching, and preview meter values before going live. Endpoint: POST /events/dry-run

​
Request

Same schema as live ingestion: 1–1,000 events per request, max 256 KB payload. 
{
  "events": [
    {
      "name": "api_call",
      "ref": "test-ref-001",
      "customerAlias": "customer-123",
      "timestamp": "2026-01-15T14:30:00Z",
      "data": {
        "endpoint": "/v1/predict",
        "tokens": 1500
      }
    }
  ]
}
FieldTypeRequiredDescription
namestringYesEvent type identifier — must match a configured meter’s eventName
refstringYesUnique idempotency key for this event
customerAliasstringYesIdentifier used to match the event to a customer
timestampstringYesISO 8601 UTC timestamp of when the event occurred
dataobjectNoArbitrary key-value payload used by meter filters and aggregations

​
Response

Returns one result object per submitted event. 
{
  "events": [
    {
      "event": {
        "name": "api_call",
        "ref": "test-ref-001",
        "customerAlias": "customer-123",
        "timestamp": "2026-01-15T14:30:00Z",
        "data": { "tokens": 1500 }
      },
      "matchedCustomer": "cust_abc123",
      "meterWithValues": [
        {
          "name": "API Calls Meter",
          "eventName": "api_call",
          "aggregationMethod": "COUNT",
          "value": 1,
          "instanceValue": null
        }
      ]
    }
  ]
}
FieldTypeDescription
eventobjectThe submitted event as it would be ingested
matchedCustomerstring | nullThe customer ID the event matched, or null if no match found
meterWithValuesarrayMeters this event would be counted against
meterWithValues[].valuenumber | nullContribution to the meter’s aggregated value
meterWithValues[].instanceValueanyFor instance-based meters: the instance identifier
If matchedCustomer is null, the event would create an anonymous customer in live ingestion. Check your customerAlias value.

​
Examples

curl -X POST "https://connect.withvayu.com/events/dry-run" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $VAYU_CLIENT_ID" \
  -d '{
    "events": [
      {
        "name": "api_call",
        "ref": "test-ref-001",
        "customerAlias": "customer-123",
        "timestamp": "2026-01-15T14:30:00Z",
        "data": { "tokens": 1500 }
      }
    ]
  }'

​
Common dry run results

ScenarioWhat you’ll see
Event matches a customermatchedCustomer is populated with the customer ID
No customer matchmatchedCustomer is null — live ingestion would create an anonymous customer
Event matches a metermeterWithValues contains the meter with a non-null value
Event name not in any metermeterWithValues is empty
Invalid event schemaEvent appears in the invalidEvents array with an error message