Quick start

Send JSON events to Telemetry and query them with SQL. This quick start sends one event, checks the table Telemetry creates, and runs a query.

Read about storage and query execution in Telemetry architecture. For a complete instrumentation example, see tracking OpenAI costs.

Prefer a shorter task-by-task path? Follow:

1. Send Your First Structured Event
2. Verify Event Ingestion and Schema
3. Write Your First Telemetry SQL Query
4. Create Your First Dashboard and Alert
5. Production Instrumentation Checklist

Get your API key

Visit the homepage to get an anonymous key in a ready-to-copy setup prompt. Use that anon_… key in the examples below; no account is needed to send your first event and query it. If you already have an account, use a read-and-write key from Team Settings → API Keys.

Anonymous queries work for 24 hours after the first event. Create an account within 7 days to keep your events and the same key. Signup remembers the trial in this browser. In another browser, select Already have an anonymous API key?, paste the key, and choose Find my data before registering. Existing users can recover the key at Keep my data, then log in. A trial with no events expires 7 days after creation.

Install Telemetry

This tutorial uses JavaScript. You can also use Python, Go, Rust, Ruby, PHP, or cURL.

npm install telemetry-sh

Log some data

Telemetry automatically creates tables when data is logged. In the following example, we log synthetic ride data to a table called uber_rides. Telemetry creates the table and its schema with city and price; every row also receives timestamp_utc.

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

telemetry.log("uber_rides", {
  city: "paris",
  price: 42
});

Explore data with our UI

First, verify the event without signing up:

const result = await telemetry.query("SELECT city, price FROM uber_rides LIMIT 10");
console.log(result);

To explore your events with charts, dashboards, and alerts, create an account and keep your data. Your existing key continues working, and registration opens the workspace containing your events. If you already have an account, link your trial.

Explore view

Use the Explore tab to filter events and build charts or tables without writing SQL.

Explore works with one table at a time. To open it:

1. Go to your team.
2. Open Tables.
3. Select a table.
4. Open the Explore tab on that table page.

Route shape:

/team/{team}/table/{table}?tab=explore

1. Pick a graph type, Samples, Table, Line, Bar, or Stacked Area.
2. Set a time range and add one or more filters.
3. Choose columns to include. You can use nested fields like data.toolName.
4. Click Run to execute and render results.

Tip: controls are draft state. Results update only when you click Run.

Synthetic example dataset

The Explore examples use synthetic test events with this structure:

{
  "timestamp_utc": "2026-02-27T12:00:00.000Z",
  "event": "tool_call",
  "status": "success",
  "data": {
    "toolName": "smart_avantis_buy",
    "args": {
      "symbol": "BTC-USD",
      "amountUsd": 2500
    }
  }
}

You can log this to a table such as agent_demo_events and use that table in Explore.

/team/{team}/table/agent_demo_events?tab=explore&graphType=samples&f=event:=:tool_call&f=data.toolName:=:smart_avantis_buy

SELECT "timestamp_utc", "event", "data.toolName", "data.args.symbol"
FROM "your_table"
WHERE timestamp_utc >= now() - INTERVAL '7 days'
ORDER BY timestamp_utc DESC
LIMIT 200

Dashboards

Dashboards let you pin Explore charts/tables and query results into one shared view.

To create and use dashboards:

1. Open any table in Explore or open a saved query result.
2. Click Add to Dashboard.
3. Choose an existing dashboard, or create a new dashboard first.
4. Give the widget a title and confirm.

Dashboard route shape:

/team/{team}/dashboard/{dashboardSlug}

Use a dashboard to compare latency, error rates, cost, and conversion metrics in one place.

Create alerts

Once you have a chart or query result, you can turn it into an alert in the Telemetry UI.

1. Open a table in Explore or run a query in Results/Chart view.
2. Click Create Alert.
3. Configure the aggregation, last N points, comparison, and threshold.
4. Set a check interval and one or more email recipients.
5. Click Create Alert to save. You will be redirected to /team/{team}/alert/{alertSlug} to monitor status and history.

Tip: leave Ignore the last data point enabled for bucketed time series, since the newest bucket is often incomplete.

For a full walkthrough, see the Alerts guide.

Interactive inline examples

/team/{team}/table/{table}?tab=explore&graphType=line&agg=p95&metric=latency_ms&time=7d

Integrate with your codebase

You can integrate Telemetry into your product or internal dashboards by querying your data with SQL through the query API.

const results =
  await telemetry.query(`
    SELECT
      city,
      AVG(price)
    FROM
      uber_rides
    GROUP BY
      city
  `);

Browse the SQL recipe library when you are ready to analyze API errors, latency percentiles, job retries, LLM cost, conversion, retention, or missing heartbeats.

For the architecture and analysis model behind those recipes, continue with SQL for Observability and Event Analytics. To run one complete synthetic workflow from ingestion through a SQL result, use the end-to-end SaaS observability demo.