# Beam

Read-only workspace analytics for agents. Keys never expire and stay valid until revoked.

Public entry point: GET https://beam.experiment.sh/api/v1.
Then start with authenticated GET /api/v1/metadata to identify the workspace and learn reports, metrics,
filter fields and types, operators, limits, pagination, date rules, and endpoint links.
Then GET /api/v1/websites to discover observed websites across all retained history.
POST /api/v1/values discovers actual dimension values with optional filters and search.
POST /api/v1/coverage inspects observed retention bounds and missing identifiers.
POST /api/v1/compare compares equal-duration periods (completed days by default).
POST /api/v1/query runs summaries, optionally zero-filled time series, and paginated
breakdowns with all metrics, ordering, and minimum-session thresholds.
Read metadata.analysis_guide and recommended_periods before interpreting data.
Sessions are not unique people; the collector uid derives from session_id.
Follow pagination.next_offset until null. Preserve the first response's date range.
All data endpoints require Authorization: Bearer <Beam API key> and use UTC.
Keys are scoped to one workspace. No arbitrary SQL or cross-workspace access.

- API docs: https://beam.experiment.sh/docs/beam-api.md
- OpenAPI: https://beam.experiment.sh/openapi.json
- Metadata: https://beam.experiment.sh/api/v1/metadata
- Websites: https://beam.experiment.sh/api/v1/websites
- Values: https://beam.experiment.sh/api/v1/values
- Query: https://beam.experiment.sh/api/v1/query
- Create keys: https://beam.experiment.sh/dashboard/settings?settings_selector=API+Keys

Reports and filter values default to midnight UTC 28 days ago through now.
Do not use the public website tracking token as an API key.

Analysis playbook: https://beam.experiment.sh/docs/analysis.md