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

# Analytics Events

> Audit log events for usage analytics and metrics access

<Info>
  Analytics events track when users view project usage data, metrics, and statistics. These events are triggered whenever analytics dashboards or API endpoints are accessed.
</Info>

## analytics.view

Triggered when a user accesses project analytics data including request counts, latency metrics, or safety statistics. This event captures the time range and granularity of the data being viewed.

### Event Schema

<ResponseField name="action" type="string" required>
  Always set to `"analytics.view"`
</ResponseField>

<ResponseField name="actor" type="object" required>
  The user viewing analytics data

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always set to `"user"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      User's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      User's full name
    </ResponseField>

    <ResponseField name="metadata" type="object" required>
      <Expandable title="properties">
        <ResponseField name="first_name" type="string" required>
          User's first name
        </ResponseField>

        <ResponseField name="last_name" type="string" required>
          User's last name
        </ResponseField>

        <ResponseField name="email" type="string" required>
          User's email address
        </ResponseField>

        <ResponseField name="impersonator_email" type="string">
          Email of admin impersonating the user
        </ResponseField>

        <ResponseField name="impersonator_reason" type="string">
          Reason for impersonation
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="targets" type="array" required>
  The project whose analytics are being viewed

  <Expandable title="target objects">
    <ResponseField name="project" type="object" required>
      <Expandable title="properties">
        <ResponseField name="type" type="string" required>
          Set to `"project"`
        </ResponseField>

        <ResponseField name="id" type="string" required>
          Project's unique identifier
        </ResponseField>

        <ResponseField name="name" type="string" required>
          Project's name
        </ResponseField>

        <ResponseField name="metadata" type="object" required>
          <Expandable title="properties">
            <ResponseField name="name" type="string" required>
              Project's name
            </ResponseField>

            <ResponseField name="organization_id" type="string" required>
              Organization containing the project
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="context" type="object" required>
  <Expandable title="properties">
    <ResponseField name="location" type="string" required>
      IP address or `"unknown"`
    </ResponseField>

    <ResponseField name="userAgent" type="string" required>
      User agent string or `"unknown"`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object" required>
  <Expandable title="properties">
    <ResponseField name="source" type="string" required>
      Page route where analytics were accessed (e.g., `"/projects/{id}/analytics"`)
    </ResponseField>

    <ResponseField name="start_date" type="string" required>
      Start of the date range for analytics query (ISO 8601 format)
    </ResponseField>

    <ResponseField name="end_date" type="string" required>
      End of the date range for analytics query (ISO 8601 format)
    </ResponseField>

    <ResponseField name="interval" type="string">
      Time interval granularity: `"hour"` or `"day"`. May be empty for summary views
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```json theme={null}
{
  "action": "analytics.view",
  "occurredAt": "2024-11-02T19:15:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JBKQ8Z...",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@company.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "project",
      "id": "proj_abc123",
      "name": "Production API",
      "metadata": {
        "name": "Production API",
        "organization_id": "org_xyz789"
      }
    }
  ],
  "context": {
    "location": "203.0.113.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
  },
  "metadata": {
    "source": "/projects/proj_abc123/analytics",
    "start_date": "2024-10-26T00:00:00.000Z",
    "end_date": "2024-11-02T23:59:59.999Z",
    "interval": "day"
  }
}
```

***

## Common Patterns

### Date Range Limitations

Analytics queries are limited to a 30-day date range. Users querying longer periods receive validation errors before the audit event is created.

### Multiple Events Per Page View

Each analytics page view generates **three separate audit events**:

1. **Summary statistics** - Overall totals, averages, and percentiles (empty `interval` field)
2. **Requests over time** - Time-series chart showing request counts (includes `interval`)
3. **Latency over time** - Time-series chart showing response times (includes `interval`)

All three events share the same `start_date` and `end_date` but differ in their `interval` values.

### Interval Selection

The `interval` field is automatically determined based on the date range:

* **Date ranges ≤ 7 days**: `interval` set to `"hour"` for hourly granularity
* **Date ranges > 7 days**: `interval` set to `"day"` for daily granularity
* **Summary views**: `interval` is empty (no time-series grouping)

<Note>
  Users do not manually select the interval—it's automatically chosen based on the selected date range to provide appropriate chart detail.
</Note>

<Tip>
  Analytics events track data access for compliance and security auditing. Organizations can use these events to monitor which team members are viewing usage metrics and when.
</Tip>

### API Key Filtering

When analytics are filtered by a specific API key, the same event structure applies. The `project` target remains the project containing the API key, and the date range parameters reflect the filtered query.