> ## 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.

# Sending events

> Sending events to Vayu

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
* **Total payload size:** 256 KB

## Example

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  from vayu_sdk import Vayu
  from datetime import datetime, timezone
  import os

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

  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))
  ```

  ```go Go theme={null}
  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))
  ```

  ```bash curl theme={null}
  curl -X PUT "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" }
        }
      ]
    }'
  ```
</CodeGroup>

## Response structure

The response includes two arrays:

* **`validEvents`** — events that were successfully ingested
* **`invalidEvents`** — events that failed validation, each with an error message

```json theme={null}
{
  "validEvents": [ { "name": "api_call", "ref": "evt_abc123", ... } ],
  "invalidEvents": []
}
```

## Immediate availability

Events are available in the API and UI immediately after ingestion.

<Note>
  Invalid events **do not** cause the entire request to fail. They are returned in the `invalidEvents` array while valid events are still processed.
</Note>