Getting Started

API Playground

The easiest way to explore and test the API is using the built-in API Playground in your Rybbit dashboard. Access it by navigating to any site and clicking "API Playground" in the sidebar.

The playground provides:

• Endpoint browser - Browse all available API endpoints
• Parameter controls - Configure request parameters with a visual interface
• Exact time ranges - Test date ranges with optional start and end times
• Live responses - See real API responses with your actual data
• Code generation - Copy ready-to-use code snippets

This is the recommended way to familiarize yourself with the API before integrating it into your applications.

Guides

Looking for what to build with the API? These end-to-end recipes chain endpoints together to solve a real problem:

• Automated Weekly Report — a scheduled digest of last week's traffic, week-over-week change, and top pages and sources.
• Find Where Users Drop Off — locate the biggest leak in a funnel, then see where the people who abandon go instead.
• Compare Channel Performance — rank acquisition channels by how well they convert, not just how much traffic they send.
• Build a Live Visitor Feed — poll the events endpoint for a real-time activity stream you can render or alert on.
• Export Events to a Warehouse — backfill your full event history and keep it in sync with an incremental job.

Authentication

All API requests must include authentication using one of the following methods:

Bearer Token (Recommended)

Authorization: Bearer your_api_key_here

Query Parameter (Testing Only)

?api_key=your_api_key_here

Generating API Keys

Rybbit has two kinds of API keys:

• Organization API keys (recommended for integrations) — the organization's own credential. They can access every site in the organization and keep working when team members leave. Only organization admins and owners can create and manage them.
• Personal API keys — act as you, with exactly your access, including any site restrictions, across every organization you belong to. Best for personal scripts and for connecting MCP clients.

Organization keys

1. Navigate to Settings → Organization in your Rybbit dashboard
2. Scroll to the Organization API Keys section (visible to admins and owners)
3. Enter a name for the key and click Create
4. Copy the key immediately (it won't be shown again)

Personal keys

1. Navigate to Settings → Account in your Rybbit dashboard
2. Scroll to the Personal API Keys section
3. Enter a name for the key and click Create
4. Copy the key immediately (it won't be shown again)

Both kinds support restricting a key to specific permissions when you create it — leave restrictions off for a full-access key.

Rate Limits (Cloud Only)

API key rate limits depend on your plan:

Self-hosted instances have no rate limits.

Common Parameters

The following parameters are shared across all analytics endpoints.

Time Parameters

All endpoints require date-based, exact datetime, or relative time parameters:

Note: You must provide either:

• All three date parameters (start_date, end_date, time_zone), OR
• All three exact datetime parameters (start_datetime, end_datetime, time_zone), OR
• Both relative parameters (past_minutes_start, past_minutes_end)

Examples

Date-based query (last 30 days):

?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York

Exact datetime query (8 AM to 10 AM in New York on Jan 15, sent as UTC):

?start_datetime=2024-01-15%2013:00:00&end_datetime=2024-01-15%2015:00:00&time_zone=America/New_York

Relative query (last 60 minutes):

?past_minutes_start=60&past_minutes_end=0

Filter Parameters

The filters parameter accepts a JSON-encoded array of filter objects to narrow down your data.

Filter Object Structure

Filter Types

Available Filter Parameters

Browser & Device

Location

Page & Traffic

UTM Parameters

User & Events

Filter Examples

[
  {
    "parameter": "country",
    "type": "equals",
    "value": ["US"]
  }
]

[
  {
    "parameter": "country",
    "type": "equals",
    "value": ["US", "CA"]
  },
  {
    "parameter": "device_type",
    "type": "equals",
    "value": ["mobile"]
  }
]

[
  {
    "parameter": "pathname",
    "type": "contains",
    "value": ["/blog"]
  }
]

[
  {
    "parameter": "pathname",
    "type": "regex",
    "value": ["^/products/[0-9]+$"]
  }
]

[
  {
    "parameter": "lat",
    "type": "greater_than",
    "value": ["37.0"]
  },
  {
    "parameter": "lat",
    "type": "less_than",
    "value": ["38.0"]
  }
]

?filters=%5B%7B%22parameter%22%3A%22country%22%2C%22type%22%3A%22equals%22%2C%22value%22%3A%5B%22US%22%5D%7D%5D

Error Responses

All endpoints return standard HTTP status codes:

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (missing or invalid API key)
• 403 - Forbidden (no access to site)
• 404 - Not Found (site doesn't exist)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error

Error Response Format

{
  "error": "Error message describing what went wrong"
}