Countly Getting Started: Setup and First API Call (2026)

Getting started overview

Integrating Countly for analytics involves a sequence of steps to configure your application for data collection. This process begins with account setup, which is necessary to generate the unique identifiers required for authentication. Following account creation, you will obtain an App Key and a Server URL, which act as the primary credentials for all data submissions. These credentials are then incorporated into your application, typically through the use of a Countly SDK, to initiate tracking. The final stage involves making a basic request, such as logging a custom event or starting a user session, to confirm that data is being transmitted and recorded correctly in your Countly dashboard.

While Countly offers a self-hosted Community Edition, this guide focuses on the general setup applicable to both cloud and self-hosted instances once the server is accessible. For detailed self-hosting setup instructions, refer to the Countly installation documentation. Countly supports a wide array of platforms via dedicated SDKs, including Android, iOS, and JavaScript, simplifying the integration process by abstracting direct API calls.

Quick Reference Table

Create an account and get keys

To begin using Countly, you need to establish an account and obtain the necessary authentication credentials: an App Key and a Server URL. The process differs slightly depending on whether you opt for Countly Cloud or a self-hosted instance.

Countly Cloud Account Creation

1. Sign Up: Navigate to the Countly pricing page and select a plan that fits your needs. The Growth Edition is the starting paid tier. Follow the registration prompts to create your account.
2. Login: Once your account is active, log into the Countly dashboard.
3. Add Application: From the dashboard, select the "Applications" section. Click on "Add Application" or a similar prompt. Provide a name for your application (e.g., "My First Mobile App") and specify its platform.
4. Retrieve App Key and Server URL: After creating the application, go to "Management" > "Applications" in the left-hand navigation. Click on your newly created application. Here, you will find your unique App Key and the Server URL (e.g., https://your-instance.count.ly). These are the critical pieces of information for authenticating your data submissions.

Self-Hosted Community Edition Setup

For the self-hosted Community Edition, you first need to install Countly on your own server. This involves setting up the server environment, installing dependencies, and deploying the Countly platform. Detailed instructions for various operating systems are available in the Countly installation guides. Once the Countly server is operational and accessible via a web browser, the steps to add an application and retrieve credentials are the same as for Countly Cloud, using your self-hosted server's URL as the Server URL.

Note: Keep your App Key and Server URL confidential. They are essential for protecting your analytics data integrity.

Your first request

With your App Key and Server URL in hand, you are ready to send your first data point to Countly. The recommended approach is to use one of Countly's various SDKs, as they handle much of the underlying API complexity, including session management, data queuing, and network requests.

This example demonstrates sending a custom event using the JavaScript SDK, commonly used for web applications. Similar patterns apply to other SDKs (e.g., Android, iOS, Node.js), with specific method names varying by language and platform.

Example: JavaScript SDK Integration

First, include the Countly JavaScript SDK in your web page. You can typically do this by adding a script tag to your HTML or by installing it via a package manager like npm.

<script type="text/javascript">
  // Countly will be available as 'Countly' global object
  var Countly = Countly || {};
  Countly.q = Countly.q || [];
  // Provide your app key and server URL to the SDK
  Countly.app_key = "YOUR_APP_KEY";
  Countly.url = "YOUR_SERVER_URL";
  
  // Optional: Set other configurations if needed
  // Countly.debug = true; // Enable debug mode for logging
  
  // Load the Countly SDK asynchronously
  (function() {
    var cly = document.createElement('script'); cly.type = 'text/javascript';
    cly.async = true;
    // Replace '/sdk/web/countly.min.js' with the actual path to your SDK file
    // If using CDN, this path will be different (e.g., 'https://cdn.jsdelivr.net/npm/countly-sdk-web@latest/lib/countly.min.js')
    cly.src = Countly.url + '/sdk/web/countly.min.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(cly, s); 
  })();
</script>

Replace "YOUR_APP_KEY" with the App Key obtained from your Countly dashboard and "YOUR_SERVER_URL" with your Countly server's URL. For example, if you are using Firebase Analytics, you would use a different SDK and initialization process.

After the SDK is loaded and initialized, you can record your first custom event:

<script type="text/javascript">
  // Ensure Countly is initialized before sending events
  Countly.q.push(["track_sessions"]); // Start session tracking
  Countly.q.push(["track_pageview"]); // Track page view
  
  // Record a custom event after the SDK is ready
  Countly.q.push(["add_event", {
    key: "first_action",
    count: 1,
    segmentation: {
      type: "initial",
      status: "success"
    }
  }]);
</script>

This code snippet will:

• Initialize session tracking (track_sessions).
• Log a page view (track_pageview).
• Record a custom event named "first_action" with associated segmentation data.

Upon execution, this data will be sent to your Countly server. You should then be able to see this event appear in your Countly dashboard under "Analytics" > "Events" or in the "Real-time" section within a few moments.

Common next steps

Once you have successfully sent your first data point to Countly, several common next steps can help you further integrate and utilize the platform's capabilities:

1. Explore Dashboard: Familiarize yourself with the Countly dashboard. Navigate through sections like "Analytics," "Users," "Crashes," and "Funnels" to understand where your data is processed and visualized.
2. Implement Advanced Tracking: Expand your tracking to include more detailed user behavior. This might involve setting up:
   • User Profiles: Record user attributes like name, email, or custom properties (e.g., Countly.q.push(["user_details"]) for JavaScript). Refer to Countly User Details API documentation.
   • Session Management: Ensure proper session starts and ends are tracked automatically by the SDK or manually configured.
   • Crash Reporting: Integrate crash reporting features to monitor application stability. This is typically enabled within the SDK initialization.
   • Error Logging: Log non-fatal errors or exceptions to identify and address issues proactively.
   • Funnels: Define conversion funnels to track user journeys and identify drop-off points.
3. Configure Remote Config: Utilize Countly Remote Config to dynamically change the behavior and appearance of your application without requiring a new app store release. This involves retrieving configuration values from the server (e.g., Countly.q.push(["remote_config_update"]) for JavaScript).
4. Set Up A/B Testing: Plan and execute A/B tests to optimize user experience and product features. Countly's A/B testing features allow you to define variations and see their impact on key metrics.
5. Webhooks and Integrations: Explore Countly's webhook functionality to send data to other systems or integrate with third-party tools. For example, if you are also using Twilio's SMS API, you might want to send Countly events to trigger notifications.
6. Review SDK Documentation: Consult the specific SDK documentation for your platform to understand all available methods and configurations fully. Each SDK offers platform-specific features and best practices for implementation.

Troubleshooting the first call

If your first data point does not appear in the Countly dashboard, consider these troubleshooting steps:

1. Verify App Key and Server URL: Double-check that the App Key and Server URL configured in your SDK or API call exactly match the credentials displayed in your Countly dashboard. A common mistake is a typo or an incorrect protocol (HTTP vs. HTTPS).
2. Check Network Connectivity: Ensure that your application has network access and can reach the Countly server. If using a self-hosted instance, confirm the server is running and accessible from your application's environment. Firewalls or proxy settings can sometimes block connections.
3. Enable SDK Debugging/Logging: Most Countly SDKs offer a debug mode or verbose logging option. Enable this feature to see console output or logs that indicate whether data is being prepared and sent, and if any errors occur during the process. For example, in the JavaScript SDK, setting Countly.debug = true; can provide valuable insights.
4. Inspect Network Requests: Use your browser's developer tools (Network tab) for web applications, or a network inspection tool (like Wireshark or Fiddler) for mobile/desktop apps, to verify that HTTP requests are being sent to your Countly server URL. Look for POST requests to the /i endpoint, which is Countly's main data ingestion endpoint. Check the request payload for your App Key and event data.
5. Review Server Logs (Self-Hosted): If you are running a self-hosted Countly instance, check the server logs for any errors or warnings related to data ingestion. Common issues can include database connection problems, disk space limitations, or incorrect permissions.
6. Time Zones and Data Processing Delays: While Countly's real-time analytics are generally fast, there might be slight delays in data processing depending on server load. Wait a few minutes after sending data before checking the dashboard. Also, ensure your system's clock is synchronized, as significant time differences can sometimes affect data reporting.
7. Consult Documentation and Support: If issues persist, refer to the Countly documentation portal for specific SDK troubleshooting guides or reach out to Countly support for assistance.