Querying analytics

Using a coding agent? Install the Lemma analytics skill, and the agent reads the catalog, builds the query, and reports the result with its window and cost caveats, over the Lemma MCP server or REST:

npx skills add uselemma/lemma --skill "lemma-analytics"

Then ask it a question, such as “Which tools failed most in the last 7 days, and what did each model cost?”

A project analytics query returns one aggregate: a count, a percentile, a sum, or an estimated cost, optionally grouped by time or by a field. You send it over REST or the Lemma Model Context Protocol (MCP) server. This page explains how a query is built, then shows examples you can copy. Every field and rule is on Analytics query API. Use a query when one number or one breakdown answers the question. For a full Analytics panel, request a preset view instead.

You need an organization API key whose scope is read or admin, plus the project id. An ingest-only key cannot call these routes. A key limited to one project works only for that project. Create the key under API Keys in the Lemma dashboard.

Find events and fields in the catalog

Every query reads one event, such as trace.processed or tool.called. The catalog lists each event with the fields you can filter and group by (dimensions), the fields you can aggregate (measures, each with its allowed aggs), and any cost_measures. It also lists filter_ops, buckets, and limits.

curl -s \
  "https://api.uselemma.ai/projects/your_project_id/analytics/catalog" \
  -H "Authorization: Bearer your_organization_api_key"

On MCP, call describe_project_analytics with project_id. A field that isn’t in the catalog can’t be queried.

Send a query

POST the query body to /projects/{project_id}/analytics/query:

curl -s -X POST \
  "https://api.uselemma.ai/projects/your_project_id/analytics/query" \
  -H "Authorization: Bearer your_organization_api_key" \
  -H "Content-Type: application/json" \
  -d @query.json

On MCP, call query_project_analytics with project_id plus the same body. MCP uses camelCase for three keys: endExclusive, groupBy, and orderBy. Field names such as agent_name stay snake_case in both.

Build the query body

A body names an event in from, a window in start and end_exclusive, and at least one measure. The window is UTC, on whole seconds, with the end exclusive. Optional keys narrow or shape the result:

Measures: what to compute, each with an alias in as, and an optional per-measure filter
Filters: conditions every counted row must match
Groups and order: split by a time bucket or a field, then sort
Join: add measures from one other event

Query request lists every key and limit.

Read the response

A response has rows, one object per group keyed by your aliases, plus truncated and the queried window. When truncated is true, further rows exist, so narrow the filters or raise limit. REST and MCP return the same snake_case shape. See Query response. An invalid query returns HTTP 400 with the reason. Query errors lists each message and its cause.

Examples

Each example below is a complete body. Save it as query.json and send it with the request in Send a query.

Daily volume and latency for one agent

Count one agent’s traces per day, with the 95th percentile of root duration. On trace.processed, root duration is root_duration_ms:

{
  "from": "trace.processed",
  "start": "2026-09-23T00:00:00.000Z",
  "end_exclusive": "2026-09-30T00:00:00.000Z",
  "filters": [
    {
      "field": "agent_name",
      "op": "eq",
      "value": "support_agent"
    }
  ],
  "group_by": [{ "bucket": "day", "as": "day" }],
  "measures": [
    { "as": "traces", "agg": "count" },
    { "as": "p95_ms", "agg": "p95", "field": "root_duration_ms" }
  ]
}

Each row is one day. p95_ms is in milliseconds.

{ "day": "2026-09-23", "traces": 120, "p95_ms": 840.5 }

Tools that fail most

Rank tools by failed calls. On tool.called, error is 1 when the tool span failed and 0 otherwise, so its sum is the failure count:

{
  "from": "tool.called",
  "start": "2026-09-23T00:00:00.000Z",
  "end_exclusive": "2026-09-30T00:00:00.000Z",
  "group_by": [{ "field": "tool", "as": "tool" }],
  "measures": [
    { "as": "calls", "agg": "count" },
    { "as": "failures", "agg": "sum", "field": "error" }
  ],
  "order_by": [{ "measure": "failures", "direction": "desc" }],
  "limit": 20
}

Divide failures by calls for the failure rate. This row is 4.5%:

{ "tool": "search_docs", "calls": 400, "failures": 18 }

Estimated cost by model

Estimate generation cost per model. generation_cost needs a model group with the alias model:

{
  "from": "generation.completed",
  "start": "2026-09-23T00:00:00.000Z",
  "end_exclusive": "2026-09-30T00:00:00.000Z",
  "group_by": [{ "field": "model", "as": "model" }],
  "measures": [{ "as": "cost", "agg": "generation_cost" }]
}

The row reports the estimate in estimated_cost_usd, not under the cost alias:

{ "model": "gpt-4o", "estimated_cost_usd": 12.4, "priced": true }

priced: false means Lemma has no list price for that model, and estimated_cost_usd is null.

Runs with errors by agent

Count each agent’s traces, and the traces where any span failed. The second measure’s filter limits it to traces with error_count above zero:

{
  "from": "trace.processed",
  "start": "2026-09-23T00:00:00.000Z",
  "end_exclusive": "2026-09-30T00:00:00.000Z",
  "group_by": [{ "field": "agent_name", "as": "agent_name" }],
  "measures": [
    { "as": "traces", "agg": "count" },
    {
      "as": "runs_with_errors",
      "agg": "count",
      "filter": { "field": "error_count", "op": "gt", "value": 0 }
    }
  ],
  "order_by": [{ "measure": "runs_with_errors", "direction": "desc" }]
}

{ "agent_name": "support_agent", "traces": 120, "runs_with_errors": 9 }

Traces and tool use per agent

Join tool calls to traces on agent_name. uniqExact on tool counts the distinct tools each agent called:

{
  "from": "trace.processed",
  "start": "2026-09-23T00:00:00.000Z",
  "end_exclusive": "2026-09-30T00:00:00.000Z",
  "group_by": [{ "field": "agent_name", "as": "agent_name" }],
  "measures": [{ "as": "traces", "agg": "count" }],
  "join": {
    "from": "tool.called",
    "on": "agent_name",
    "measures": [
      { "as": "tool_calls", "agg": "count" },
      { "as": "tools_used", "agg": "uniqExact", "field": "tool" }
    ]
  }
}

{ "agent_name": "support_agent", "traces": 120, "tool_calls": 640, "tools_used": 7 }

Cost estimates

trace_cost and generation_cost are estimates from recorded token counts and public list prices, not an invoice. Cost fields lists what each adds to a row, including cost_lower_bound when the estimate can be low.

Preset views

GET /projects/{project_id}/analytics returns one dashboard panel. Pass one view. MCP has one tool for each view. View names, MCP tools, parameters, and responses are on Analytics query API.

Analytics query API

Every event, field, rule, error, and preset view.

Analytics

Dashboard charts for volume, latency, errors, tools, models, and cost.

Analytics catalog

Events, fields, filters, and limits for a project query.

Query project analytics

The REST operation for one aggregate.

Analytics telemetry

SDK fields the aggregates are computed from.

​Find events and fields in the catalog

​Send a query

​Build the query body

​Read the response

​Examples

​Daily volume and latency for one agent

​Tools that fail most

​Estimated cost by model

​Runs with errors by agent

​Traces and tool use per agent

​Cost estimates

​Preset views

​Related pages

Analytics query API

Analytics

Analytics catalog

Query project analytics

Analytics telemetry

Find events and fields in the catalog

Send a query

Build the query body

Read the response

Examples

Daily volume and latency for one agent

Tools that fail most

Estimated cost by model

Runs with errors by agent

Traces and tool use per agent

Cost estimates

Preset views

Related pages