Getting Started

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

API keys are user-scoped and grant organization-level access:

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

Rate Limits

• 500 requests per 10 minutes per API key
• Keys are tied to your user account and grant access to all sites in your organization(s)

Common Parameters

The following parameters are shared across all analytics endpoints.

Time Parameters

All endpoints require either date-based or relative time parameters:

Note: You must provide either:

• All three date parameters (start_date, end_date, 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

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"
}

Best Practices

1. Cache responses - Analytics data doesn't change frequently. Cache for at least 5-10 minutes.
2. Use date ranges - For recent data, use past_minutes_start/end. For historical data, use start_date/end_date.
3. Filter strategically - Apply filters to reduce data transfer and improve performance.
4. Paginate results - Use the limit and page parameters for large datasets.
5. Monitor rate limits - Implement exponential backoff if you receive 429 responses.

Rate Limiting

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": "Rate limit exceeded. Maximum 500 requests per 10 minutes per API key."
}

Wait for the rate limit window to reset before making additional requests.