Countly API Documentation
Welcome to the Countly Server API reference. This documentation covers all read (GET /o/...) and write (POST /i/...) endpoints across the core platform and enterprise plugins.
Authentication
All API calls require authentication. There are multiple ways to authenticate depending on the type of endpoint.
API Key vs App Key
Countly uses two different keys for different purposes:
| Key | Purpose | Used by | How to obtain |
|---|---|---|---|
api_key | Dashboard / server-side access. Grants full read & write access as the associated user. Use for management, analytics reads, and any server-to-server call. | Server / admin scripts | Management → API Key in the dashboard |
app_key | SDK / client-side access. Identifies the application and allows only data ingestion (write) endpoints (/i, /i/...). It is safe to embed in client apps because it cannot read data. | SDKs, client apps | Management → Apps → App Key |
Rule of thumb: if the endpoint path starts with
/iand is called from a client device or SDK, useapp_key. For everything else (reading data via/o, managing apps, users, etc.) useapi_keyor an auth token.
Auth Token (parameter)
Instead of api_key, you can pass an auth token as the auth_token query parameter or in the request body:
GET /o?auth_token=YOUR_TOKEN&app_id=APP_ID&method=...
Auth tokens can be scoped to specific apps, endpoints, and have a configurable TTL. Create them via the Token API.
Auth Token (header)
You can also pass the auth token in the countly-token HTTP header:
GET /o?app_id=APP_ID&method=...
countly-token: YOUR_TOKEN
This is the recommended approach for server-to-server integrations as it keeps tokens out of URLs and server logs.
Quick Reference
| Scenario | Key / Token | Example parameter |
|---|---|---|
| SDK sending events | app_key | app_key=APP_KEY |
| SDK sending crash data | app_key | app_key=APP_KEY |
| Reading analytics from server | api_key or auth_token | api_key=API_KEY |
| Managing apps / users | api_key or auth_token | countly-token: TOKEN |
| Scoped, time-limited access | auth_token | auth_token=TOKEN |
Core API
The core platform ships with every Countly installation.
| Category | Description |
|---|---|
| Analytics | Sessions, users, and technology metrics |
| App Users | User profiles, exports, and data subjects |
| Apps | Create, update, and delete applications |
| Bulk | Batch request ingestion |
| Events | Custom event tracking and management |
| Export | Data export and downloads |
| User Management | Dashboard user accounts and permissions |
| Token | Authentication token management |
| Tasks | Long-running task status and results |
| SDK | SDK configuration endpoints |
| System | Server health, jobs, and configuration |
| Plugins | Plugin state and management |
Enterprise Plugins
Features marked with Ⓔ require an Enterprise license.
Analytics & Insights
| Plugin | Description |
|---|---|
| Drill Ⓔ | Raw event querying with filters and projections |
| Funnels Ⓔ | Multi-step conversion funnels |
| Flows Ⓔ | User flow visualization |
| Cohorts Ⓔ | Behavioral user segments |
| Formulas Ⓔ | Calculated metrics from existing data |
| Retention Segments Ⓔ | Retention analysis by cohort |
| Active Users Ⓔ | Daily / weekly / monthly active users |
| Concurrent Users Ⓔ | Real-time online user count |
| Activity Map Ⓔ | Geographic session heatmaps |
| Times of Day | Session distribution by hour |
User Engagement
| Plugin | Description |
|---|---|
| Push | Push notification campaigns |
| Surveys Ⓔ | In-app surveys (NPS, ratings, feedback) |
| Remote Config | Server-side feature flags and variables |
| AB Testing Ⓔ | Experiment variants and results |
| Content Ⓔ | In-app content management |
| Journey Engine Ⓔ | Automated user journeys |
| AI Assistants Ⓔ | AI-powered insights |
Crashes & Errors
| Plugin | Description |
|---|---|
| Crashes | Crash reporting and grouping |
| Crash Symbolication Ⓔ | Symbol file upload and stack trace resolution |
| Crashes Jira Ⓔ | Jira integration for crash groups |
| Error Logs | Server error log viewer |
Security & Authentication
| Plugin | Description |
|---|---|
| LDAP Ⓔ | LDAP / Active Directory SSO |
| Active Directory Ⓔ | Azure AD integration |
| OIDC Ⓔ | OpenID Connect SSO |
| Okta Ⓔ | Okta SSO integration |
| Cognito Ⓔ | AWS Cognito integration |
| Two-Factor Auth | TOTP-based 2FA |
| reCAPTCHA | Login reCAPTCHA protection |
| Block Ⓔ | IP / device blocking |
Data & Infrastructure
| Plugin | Description |
|---|---|
| ClickHouse | ClickHouse analytics backend |
| Kafka | Kafka event streaming |
| Data Manager Ⓔ | Event schema and transformation rules |
| Data Migration | Import / export server data |
| Config Transfer Ⓔ | Transfer settings between servers |
| DBViewer | Direct database collection browser |
Dashboards & Reporting
| Plugin | Description |
|---|---|
| Dashboards | Custom dashboard builder |
| Alerts | Metric-based alert rules |
| Reports | Scheduled email reports |
Conventions
- Read endpoints —
GET /o/...— retrieve data; requireapi_key+app_id. - Write endpoints —
POST /i/...— create or modify data; may requireapp_keyorapi_key. - Responses — JSON. Successful calls return the result directly; errors return
{"result": "Error message"}. - Pagination — List endpoints accept
iDisplayStartandiDisplayLengthparameters.