> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Report Client Events

> Report JavaScript errors, logs, traces, and performance metrics from your frontend

<Note>
  This endpoint does not require API key authentication. Use your beacon public key (`bpk_...`) in the request body.
</Note>

## Body Parameters

<ParamField body="key" type="string" required>
  Your beacon public key (`bpk_...`) or API key
</ParamField>

<ParamField body="events" type="array" required>
  Array of events to report
</ParamField>

### Event Object

<ParamField body="events[].type" type="string" required>
  Event type: `error`, `log`, `trace`, `vital`, `page_load`, `slow_request`
</ParamField>

<ParamField body="events[].timestamp" type="number" required>
  Unix timestamp in milliseconds
</ParamField>

<ParamField body="events[].session_id" type="string" required>
  Unique session identifier
</ParamField>

<ParamField body="events[].url" type="string">
  Page URL where event occurred
</ParamField>

<ParamField body="events[].service" type="string">
  Service/app name
</ParamField>

<ParamField body="events[].environment" type="string">
  Environment: `production`, `staging`, `development`
</ParamField>

<ParamField body="events[].data" type="object">
  Event-specific data (error message, stack trace, etc.)
</ParamField>

<ParamField body="user" type="object">
  User context: `{ id, email, username }`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether events were recorded
</ResponseField>

<ResponseField name="received" type="integer">
  Number of events received
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://kodostatus.com/api/beacon" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "bpk_your_key_here",
      "events": [{
        "type": "error",
        "timestamp": 1704844800000,
        "session_id": "sess_abc123",
        "url": "https://example.com/dashboard",
        "service": "my-app",
        "environment": "production",
        "data": {
          "message": "Cannot read property x of undefined",
          "stack": "TypeError: Cannot read property...",
          "type": "TypeError"
        }
      }],
      "user": { "id": "user123", "email": "user@example.com" }
    }'
  ```

  ```javascript Browser SDK theme={null}
  import { Beacon } from '@kodo-status/beacon';

  const beacon = new Beacon({
    key: 'bpk_your_key_here',
    service: 'my-app',
    environment: 'production'
  });

  // Errors are captured automatically
  // Or report manually:
  beacon.captureError(new Error('Something went wrong'));
  beacon.log('info', 'User clicked checkout');
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "received": 1,
    "signatures_updated": 1,
    "logs_stored": 0,
    "traces_stored": 0,
    "spans_stored": 0
  }
  ```
</ResponseExample>