canonical: https://jentic.com/apis/keen.io/keen-io

# Keen IO Analytics API

The Keen IO Analytics API lets developers stream custom event data into Keen, then run aggregations such as counts, sums, averages, percentiles, and unique counts directly through HTTP queries. It is designed for embedding analytics into applications, building customer-facing dashboards, and powering custom reports without standing up a separate data pipeline. Authentication uses scoped Read, Write, and Master keys passed via the Authorization header, so write traffic from clients can be isolated from query and admin traffic. The 13 endpoints cover event ingestion, event collection management, property inspection, and the full set of analytical query types.

## For AI agents

Stream events into Keen IO and run count, sum, average, percentile, and unique-count queries against collected event data via HTTP for custom analytics dashboards.

## Scope

Does not handle web tracking pixels, session replay, or marketing attribution - use for event ingestion and aggregate analytical queries only.

## Capabilities

- Record single events or batched events into named collections via the events endpoints
- Run count, count_unique, sum, average, minimum, maximum, median, and percentile queries over event data
- Inspect schema and individual properties of an event collection before querying
- Delete an event collection or specific events that match a filter
- Scope client-side traffic with a Write key while keeping query access on a separate Read key
- Group and filter analytical queries by arbitrary event properties for cohort and segment analysis

## Use cases

### Embedded Customer-Facing Dashboards

Power per-customer analytics dashboards inside a SaaS product by tagging events with the customer ID at write time and running filtered count, sum, and average queries at read time. Keen IO handles the storage and aggregation tier so each tenant sees only their own data, and Read keys can be scoped per tenant. Most teams ship a working embedded dashboard in days rather than weeks because no warehouse or query engine has to be provisioned.

Example prompt: Run a POST `/projects/{projectId}/queries/count_unique` against the page_views collection filtered by customer_id=acme to return monthly active users for one tenant

### Product Usage Telemetry

Capture in-product events such as feature_used, button_clicked, or workflow_completed by streaming them into Keen collections, then aggregate by property to identify which features drive engagement. Counts, unique counts, and group-by queries return the metrics needed for funnel and retention analysis without writing SQL. The integration is two endpoints on the write side and a single query endpoint on the read side, so teams can instrument a product in an afternoon.

Example prompt: Send a POST to `/projects/{projectId}/events/feature_used` with properties feature='export_csv' and user_id, then query count grouped by feature for the last 7 days

### Operational Metrics and Alerting

Record latency, error, and throughput events from backend services into a metrics collection and run percentile and maximum queries on a schedule to track SLO compliance. Keen IO supports filtered queries on numeric properties so an agent or monitoring job can ask 'what is the p95 latency over the last hour' and trigger an alert when the result crosses a threshold. Setup takes hours rather than the days needed to stand up a self-hosted time-series stack.

Example prompt: Run POST `/projects/{projectId}/queries/percentile` on the api_requests collection with target_property='latency_ms' and percentile=95 over the last 1 hour

### AI Agent Analytics Workflows

An AI agent uses Jentic to discover the Keen analytics endpoints by intent, then writes events into a collection during a workflow and queries aggregates at the end of the run to produce a result summary. Because Keen exposes the same query primitives (count, sum, average, percentile) over HTTP, the agent can compose them without learning SQL or a vendor-specific dashboard tool. Jentic injects scoped Read or Write keys per call so the agent never holds the Master key.

Example prompt: Use Jentic to load the Keen count_unique operation, supply target_property=user_id and a 24-hour timeframe, and return the result to the agent for downstream reasoning

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/projects/{projectId}/events/{collectionName}` | Record a single event into a collection |
| POST | `/projects/{projectId}/events` | Record a batch of events across multiple collections |
| POST | `/projects/{projectId}/queries/count` | Run a count query over a collection |
| POST | `/projects/{projectId}/queries/count_unique` | Count distinct values of a property |
| POST | `/projects/{projectId}/queries/sum` | Sum a numeric property across events |
| POST | `/projects/{projectId}/queries/average` | Average a numeric property across events |
| GET | `/projects/{projectId}/events/{collectionName}/properties/{propertyName}` | Inspect the schema of a property |
| DELETE | `/projects/{projectId}/events/{collectionName}` | Delete events matching a filter |

## Key resources

- **Events** — Write single or batched events into named collections and inspect what has been recorded
- **Queries** — Run count, count_unique, sum, average, minimum, maximum, median, and percentile aggregations over events
- **Properties** — Read the schema of a property on a collection to inform query construction

## Why Jentic

- **Setup:** Wiring the Keen IO Analytics API by hand means managing separate Read, Write, and Master keys in the Authorization header, calling api.keen.io/3.0, and building the query bodies for counts and aggregations yourself. Through Jentic you install once, import the Keen IO Analytics API from the API Directory, store the keys once, and your agent calls it.
- **Permission scoping:** Keen puts the project id in the URL path (`/projects/{projectId}/...`), so a rule can pin your agent to one project: it can ingest events and run aggregate queries there and nothing else. You choose the operations it may call, so a destructive one like deleting an event collection is not included unless you add it.
- **Credential handling:** Your Keen Read, Write, and Master keys are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'count unique users in Keen' or 'record an event', and Jentic returns the matching Keen operation with its input schema so the agent calls the right endpoint without browsing Keen's docs.

## Related APIs

- **Mixpanel** — Mixpanel is a product analytics platform with broader funnel, retention, and cohort tooling than Keen's query primitives.
- **Amplitude** — Amplitude is a behavioural analytics platform with prebuilt user-journey analysis on top of event streams.
- **Segment** — Segment captures and routes event streams; Keen IO is one downstream destination for storage and querying.
- **PostHog** — PostHog is an open-source product analytics platform with self-hostable event capture and querying.

## FAQ

### What authentication does the Keen IO Analytics API use?

The API uses scoped API keys passed in the Authorization header. Keen defines four scopes - Master, Read, Write, and a generic Authorization key - and each is sent as the value of the Authorization header on every request. Through Jentic, these keys live in the encrypted vault and are injected per call, so an agent making a write request only ever sees the scoped Write key.

### Can I run a unique-count query with the Keen IO Analytics API?

Yes. POST to `/projects/{projectId}/queries/count_unique` with the event_collection name, the target_property to count distinct values of, and a timeframe. The same pattern works for count, sum, average, minimum, maximum, median, and percentile queries - each is its own endpoint under `/queries/.`

### What are the rate limits for the Keen IO Analytics API?

The OpenAPI spec does not declare numeric rate limits. Keen historically enforces per-project quotas tied to the plan, with stricter limits on query endpoints than on event-write endpoints. If you receive HTTP 429 responses, back off and retry; for sustained high write volumes use the batched POST `/projects/{projectId}/events` endpoint to reduce request count.

### How do I record an event through Jentic?

Search Jentic with a query like 'record an event in keen' to find the POST `/projects/{projectId}/events/{collectionName}` operation, load its schema, and execute it with the projectId, collection name, and event body. Jentic injects the Write key automatically. The full flow is pip install jentic, then client.search, client.load, and client.execute.

### Can I delete events from a Keen collection?

Yes. DELETE `/projects/{projectId}/events/{collectionName}` removes events from the named collection and accepts a filters parameter so you can scope deletion to events matching property conditions. This requires the Master key - a Write key is not sufficient for delete operations.

### Does the Keen IO Analytics API support property inspection?

Yes. GET `/projects/{projectId}/events/{collectionName}/properties/{propertyName}` returns metadata about a property on a collection, which is useful for an agent that needs to confirm a property exists and what type it has before constructing a query against it.

### Can I limit what my agent is allowed to do with the Keen IO Analytics API?

Yes. Because you run Jentic One yourself, your own rules decide which Keen operations and keys the agent may use, and Keen puts the project id in the URL path (`/projects/{projectId}/...`), so a rule can pin the agent to a single project where it can ingest events and run count, count_unique, sum, average, and percentile queries and nothing else. You choose the operations it may call, so a destructive one like DELETE `/projects/{projectId}/events/{collectionName}` is left out unless you add it. Your scoped Read, Write, and Master keys are stored by your own instance and injected only on the calls you allow.