Keen IO Getting Started: Setup & First API Call (2026)

Getting started overview

Keen IO is a developer-centric analytics platform designed for collecting, storing, and querying custom event data. The getting started process involves setting up an account, obtaining necessary API credentials, and making an initial API call to confirm data collection. Developers typically integrate Keen IO by sending event data from their applications and then querying that data to build custom analytics dashboards or reports. The platform emphasizes flexibility, allowing users to define their event structures and analytical queries.

The core steps to get started with Keen IO include:

1. Account Creation: Register for a Keen IO account, which includes a free developer tier.
2. Credential Retrieval: Locate your Project ID and API Keys (Write Key, Read Key, Master Key) within the Keen IO project dashboard.
3. SDK or API Integration: Choose an SDK for your preferred language or interact directly with the Keen IO REST API to send your first event.
4. Data Validation: Verify that the event data has been successfully collected and is queryable within the Keen IO platform.

This guide focuses on the initial setup and a basic event collection request. Further steps involve more complex data modeling, querying, and visualization, which are covered in the Keen IO official documentation.

Quick reference table

Create an account and get keys

To begin collecting data with Keen IO, you must first create an account and then retrieve the API credentials required for authentication. Keen IO offers a Developer Plan free tier that supports up to 100,000 events per month, which is suitable for initial testing and small projects.

Account creation process

1. Navigate to the Keen IO pricing page.
2. Select the "Developer" plan or a suitable paid plan based on your needs.
3. Follow the prompts to enter your email address, create a password, and provide any other requested information.
4. Once registered, you will be directed to your Keen IO project dashboard.

Retrieving API keys

API keys are essential for authenticating your requests to the Keen IO API. There are three primary types of keys:

• Project ID: A unique identifier for your Keen IO project.
• Write Key: Used for sending (writing) event data to your project. Keep this key secure.
• Read Key: Used for querying (reading) event data from your project.
• Master Key: Provides full administrative access, including deleting projects and data. This key should be kept highly confidential and only used for administrative tasks.

To retrieve your keys:

1. From your Keen IO dashboard, select the project you wish to work with.
2. Go to the "Access" or "Project Settings" section.
3. Locate the "API Keys" or "Project Access" tab.
4. Your Project ID, Write Key, and Read Key will be displayed there. Copy these values for use in your application.

The Keen IO authentication documentation provides further details on securing and managing your API keys.

Your first request

After obtaining your API keys, the next step is to send your first event. This confirms that your credentials are correct and that data can be successfully ingested into your Keen IO project. You can use one of Keen IO's official SDKs or make a direct HTTP POST request.

Using the JavaScript SDK

The JavaScript SDK is commonly used for web applications. First, install the SDK:

npm install keen-js
# or
yarn add keen-js

Then, initialize the client and send an event:

import Keen from 'keen-js';

const client = new Keen({
  projectId: 'YOUR_PROJECT_ID',
  writeKey: 'YOUR_WRITE_KEY'
});

// Send a 'page_view' event
client.recordEvent('page_views', {
  page_title: 'Homepage',
  user_id: 'user123',
  timestamp: new Date().toISOString()
})
.then(res => {
  console.log('Event recorded successfully:', res);
})
.catch(err => {
  console.error('Error recording event:', err);
});

Replace 'YOUR_PROJECT_ID' and 'YOUR_WRITE_KEY' with your actual credentials.

Using the Python SDK

For Python applications, install the SDK:

pip install keen

Then, initialize the client and send an event:

import keen

client = keen.KeenClient(
    project_id='YOUR_PROJECT_ID',
    write_key='YOUR_WRITE_KEY'
)

# Send a 'user_signup' event
client.add_event('user_signups', {
    'user_id': 'new_user_456',
    'plan': 'premium',
    'timestamp': keen.utils.get_timestamp()
})

print("Event sent successfully.")

Again, substitute your actual Project ID and Write Key.

Direct HTTP POST request

You can also send events directly via the REST API using tools like curl or any HTTP client. The endpoint for event collection is https://api.keen.io/3.0/projects/{project_id}/events/{collection_name}.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_WRITE_KEY" \
  -d '{ "event_property_1": "value1", "event_property_2": 123 }' \
  "https://api.keen.io/3.0/projects/YOUR_PROJECT_ID/events/my_first_collection"

Ensure you replace YOUR_PROJECT_ID, YOUR_WRITE_KEY, and customize the JSON payload and collection_name (e.g., my_first_collection) as needed. The Authorization header should contain your Write Key.

Common next steps

Once you've successfully sent your first event, consider these common next steps to further integrate and utilize Keen IO:

• Explore Data: Use the Keen IO Explorer within your dashboard to view the events you've collected and run basic queries. This helps confirm data integrity and collection.
• Define Event Schema: While Keen IO is schema-less by default, it's good practice to plan your event structures. Define consistent event names and property types to ensure clean data for analysis. The Keen IO data modeling guide offers best practices.
• Implement More Event Tracking: Identify key user actions or system events in your application that you want to track. Implement additional event collection using the appropriate SDKs or direct API calls.
• Build Queries: Learn how to construct more complex queries using the Keen IO Query API to extract insights from your data. This often involves aggregations, filters, and group-bys.
• Create Dashboards: Develop custom dashboards to visualize your data. Keen IO provides tools for basic visualization, or you can integrate with third-party visualization libraries and business intelligence tools.
• Secure API Keys: Implement best practices for securing your API keys, especially the Write Key. For client-side applications, consider proxying event collection through your own backend to prevent exposing the Write Key. For server-side applications, use environment variables for key storage. Industry standards recommend against hardcoding API keys directly into source code, as detailed by sources like Google Cloud's API key security guidelines.

Troubleshooting the first call

If your first API call to Keen IO doesn't work as expected, here are some common issues and troubleshooting steps:

• Incorrect API Keys or Project ID: Double-check that you have copied the correct Project ID and Write Key. Ensure there are no leading or trailing spaces. A common error is using the Read Key for writing events, or vice-versa.
• Authorization Header Missing or Incorrect: For direct HTTP requests, ensure the Authorization header is present and correctly formatted with your Write Key. For SDKs, confirm the key is passed correctly during client initialization.
• Network Connectivity Issues: Verify that your application has internet access and can reach api.keen.io. Temporarily disable any firewalls or proxies if you suspect they are interfering.
• JSON Payload Errors: If sending a direct HTTP request, ensure your JSON payload is valid and correctly formatted. Malformed JSON can result in a 400 Bad Request error.
• Client-Side Blocking (CORS): If sending events from a web browser, ensure your Keen IO project is configured to allow requests from your domain. Keen IO handles CORS support, but incorrect setup on your end can cause issues.
• Event Collection Name: Ensure the event collection name is valid. It should be a string and adhere to naming conventions (e.g., no special characters other than underscores and hyphens).
• Check Keen IO Status Page: Occasionally, there might be service interruptions. Check the Keen IO API status or their official communication channels for any ongoing issues.
• Consult SDK Documentation: Each SDK has specific error handling mechanisms. Refer to the specific Keen IO SDK documentation for detailed error messages and guidance.

When troubleshooting, always check the response from the API call for specific error messages, as these often provide direct clues about the problem.