Artifacts

Overview

An Artifact is a self-contained HTML page that your coding agent builds from your Latitude data: a one-off report that answers a specific question, or a KPI dashboard you reopen every morning with fresh numbers. Latitude doesn’t ship a dashboard builder. Instead, everything you see in the Latitude web app is exposed as operations over the MCP, the CLI, the API and the SDKs: traces, sessions, spans, tools, users, memory, signals, incidents, experiments, saved searches, and a composable analytics query on top of all of it. You ask your agent a question, the agent makes the calls, renders the page and writes the findings. Latitude provides the data; the agent provides the page. You may never need to open the Latitude web app.

Install the latitude-artifacts skill so your agent asks the right questions, pulls the right data and renders every artifact in the same Latitude design language, with light and dark themes:

npx skills add https://github.com/latitude-dev/skills --skill latitude-artifacts

Three ways to build one

Modality	How it works	Good for
One-off report	You ask in the conversation. The agent calls the MCP, embeds the results in the HTML and writes the findings.	A specific question, a post-mortem, “what happened this week”
Refreshable dashboard	The agent writes the page once, plus a small script that re-pulls the data through the API and rewrites the page’s data blob. You run it, or cron or CI runs it.	KPIs you open every morning
Agent-refreshed	A scheduled agent run executes the refresh script and rewrites the findings too.	A dashboard with fresh commentary

The page is the same in all three. It embeds the data as a JSON blob, so a refresh never touches the layout, and it never calls the Latitude API from the browser. Refreshable artifacts need an API key in the environment.

Example prompts

Paste any of these into an agent connected to the Latitude MCP (or with the CLI authenticated). Each one gives the agent a question, a window and a target; the latitude-artifacts skill fills in the rest, and asks a couple of short questions when something is unclear.

One-off reports

Build an artifact of this project's LLM reliability and cost over the last 30 days: volume, error rate, p95 latency and spend, broken down by model and by tool, with what changed versus the previous 30 days.

How are users interacting with my agent's memory? Build an artifact for the last 14 days: which memory stores exist and how big they are, how much they change per day, who reads and writes them, what gets retrieved most, and what memory costs per session.

Which of my agent's tools fail the most, and why? Build an artifact with per-tool call volume, error rate and p95 latency, the clustered error messages for the three worst tools, and the ten slowest tool calls.

Yesterday's error rate spiked. Build a post-mortem artifact: when it started and ended, which models, tools and users were affected, the signals and incidents that fired, and the most likely root cause with links to example traces.

Compare gpt-4.1 and claude-sonnet-4 in this project over the last two weeks: latency percentiles, cost per trace, error rate, cache hit rate and tool-call counts, as an artifact with a short recommendation.

Build a weekly quality digest artifact: ongoing, new and escalating signals with their occurrence trends, incidents by severity, behaviour clusters that grew or shrank, and the pass rate of every signal broken down by model.

Refreshable dashboards

Create a refreshable artifact I can open every morning with yesterday's numbers: traces, sessions, unique users, error rate, p95 latency, spend and tokens, each with a 14-day trend, plus the top 10 tools by calls and the ongoing signals. Save it to artifacts/daily.html with a refresh script I can run from this repo.

Set up a weekly ops artifact for this project that refreshes on a GitHub Actions schedule every Monday at 08:00 UTC and publishes to GitHub Pages. Sections: reliability, cost by model and provider, tool failures, new users, and incidents.

Build a per-customer usage artifact refreshed daily: for each identified user, traces, sessions, tokens, cost and the tools they hit most, sorted by spend, with a cost histogram and the users whose spend grew fastest week over week.

What the agent can query

Every read below is one operation with the same name on the MCP, the CLI, the API and the SDKs: the MCP tool listTools is latitude tools list on the CLI, GET /v1/projects/{projectSlug}/tools on the API and client.tools.list(...) in the SDKs. The agent reads each operation’s schema before calling it; the live catalog is the API reference.

Question	Operations
Any aggregate over traces, sessions, spans, scores, behaviours or moments: counts, rates, latency percentiles, cost, tokens, by any dimension, over time	`queryAnalytics`
The overview series the Latitude UI shows, in 12-hour buckets	`getTraceAnalytics`, `getSessionAnalytics`, `getSignalAnalytics`
Rows: slowest or most expensive traces, failing sessions, individual spans across traces	`listTraces`, `listSessions`, `querySpans`, `listSessionTraces`
The conversation behind one row	`getTrace`, `getSession`, `listTraceSpans`, `getTraceSpan`
Tools: catalog with usage metrics, call histograms, parameters, error clusters, co-occurrence, where a tool is used, recent calls	`listTools`, `getTool`, `getToolCallHistogram`, `getToolParameters`, `getToolErrors`, `getToolCoOccurrence`, `getToolContext`, `listToolCalls`
Users: unique and new users, leaderboards by cost and volume, one user’s profile, activity, usage mix, signals, behaviours, memory stores	`getUsersOverview`, `listUsers`, `getUser`, `getUserActivity`, `getUserUsage`, `listUserSignals`, `listUserBehaviours`, `listUserMemoryStores`
Memory: stores and their size, snapshots at a point in time, diffs between two dates, record history and reads, who accesses what, per-session and per-trace footprint	`listMemoryStores`, `getMemoryStore`, `getMemoryStoreDiff`, `listMemoryStoreUsers`, `getMemoryRecord`, `getMemoryRecordChange`, `listMemoryRecordReads`, `listMemoryRecordUsers`, `getSessionMemory`, `getSessionMemoryChanges`, `getTraceMemory`, `getTraceMemoryChanges`
Signals and incidents: lifecycle groups, trends, evidence, contributing traces, incidents by severity, monitors	`listSignals`, `getSignal`, `getSignalTrend`, `listSignalTraces`, `listIncidents`, `listMonitors`, `listMonitorIncidents`
Experiments, saved searches, annotations	`listExperiments`, `getExperiment`, `listSavedSearches`, `listSavedSearchTraces`, `listTraceAnnotations`

All of these are read-only. The write operations (creating signals, monitors, datasets, annotations) are available to the same agent, so an artifact can end with an action: “create a monitor on this” or “save this search”.

The aggregate query: `queryAnalytics`

Most tiles and charts in an artifact are one queryAnalytics call: a metric over a filtered stream, optionally split by a breakdown and bucketed over time.

Metric: the number each row reduces to (count, errorRate, percentile(duration), sum(cost), …).
Breakdown: the dimension to split across, one row per value (model, tool, signalId, …).
Time bucket: optional granularity (hour, day, week) that turns a number into a trend.

“Error rate by model, weekly” is metric errorRate × breakdown model × bucket week. Swap any axis for the next chart; there is no new endpoint to learn.

Stream	What it measures	Metrics	Break down by
`traces` / `sessions` / `spans`	requests, conversations, operations	`count`, `errorRate`, `cacheHitRate`, `sum`/`min`/`max`/`avg`/`median` of `duration`\|`cost`\|`tokens`, plus `percentile` (`{ kind: "percentile", field, p }`, `p` 1–99)	`model`, `provider`, `service`, `tool`, `tag`, `status` (+ `name`/`userId` on traces, `operation` on spans)
`scores` (signals)	scored occurrences	`count`, `passRate`, `errorRate`, `avg`/`min`/`max`/`median` of `value`	`signalId`, `source`, `model`, `provider`, `service`, `tool`, `tag`
`behaviors`	clustered behaviours	`count`, `avg`/`min`/`max`/`median` of `confidence`	`cluster`, `session`, `method`
`moments`	labeled conversation moments	`count`, `avg`/`min`/`max`/`median` of `confidence`\|`coherence`	`kind`, `actor`, `session`

Values come back in human units: duration in seconds, cost in dollars, rates (errorRate, cacheHitRate, passRate) as a 0–1 fraction. Opaque breakdown keys such as signalId and cluster carry a human label. filters accepts the same DSL as listTraces (see Filters).

// Error rate by model, weekly, last 30 days
queryAnalytics({
  stream: "traces", metric: { kind: "errorRate" }, breakdown: "model",
  timeBucket: { unit: "week" },
  range: { fromIso: "2026-08-08T00:00:00Z", toIso: "2026-09-07T00:00:00Z" }
})

// 95th-percentile latency by tool, last 7 days
queryAnalytics({
  stream: "traces", metric: { kind: "percentile", field: "duration", p: 95 }, breakdown: "tool",
  range: { fromIso: "2026-08-31T00:00:00Z", toIso: "2026-09-07T00:00:00Z" }
})

// Cost by provider
queryAnalytics({
  stream: "traces", metric: { kind: "sum", field: "cost" }, breakdown: "provider",
  range: { fromIso: "2026-08-31T00:00:00Z", toIso: "2026-09-07T00:00:00Z" }
})

// Conversation fallout: moment count by kind
queryAnalytics({
  stream: "moments", metric: { kind: "count" }, breakdown: "kind",
  range: { fromIso: "2026-08-31T00:00:00Z", toIso: "2026-09-07T00:00:00Z" }
})

Each returns a tidy series, [{ key?, label?, bucketStart?, value }], small enough to embed inline no matter how many traces it spans. For a “versus the previous period” delta, the agent runs the same query with the range shifted back and computes the difference.

Row-level widgets

For a “top 10 slowest tool calls” table, the agent needs rows rather than an aggregate. querySpans lists individual spans across traces; listTraces and listSessions do the same at trace and session grain.

querySpans({
  filters: { operation: [{ op: "eq", value: "execute_tool" }] },
  range: { fromIso: "2026-08-31T00:00:00Z", toIso: "2026-09-07T00:00:00Z" },
  orderBy: { field: "duration", direction: "desc" },
  limit: 10
})

Row-level responses use wire units: traces carry durationNs and costTotalMicrocents, while spans carry costTotalMicrocents plus startTime and endTime, so a span’s duration is the difference between the two timestamps. The skill normalizes all of it to seconds and dollars before rendering. Row-level data can also carry conversation content, so the skill embeds ids and summaries by default and links to the trace in Latitude rather than copying the messages.

A worked example: memory

“How are users interacting with my agent’s memory?” becomes five questions, each mapped to an operation:

Question	Call	Widget
Which stores exist, how big are they, how many sessions and users touch them?	`listMemoryStores`	table with inline bars
How much did each store change over the window?	`getMemoryStoreDiff` per store, `from` → `to`	stacked bar: added, updated, removed
Who reads and writes the busiest store?	`listMemoryStoreUsers`, `listMemoryRecordUsers`	table
What do users actually retrieve?	`listMemoryRecordReads` on the top records	table of query texts and token counts
What does memory cost per session?	`getSessionMemory` on a sample, `queryAnalytics` on `sessions` for the baseline	KPI tiles with deltas

The agent renders those five widgets, then writes the findings: which store is growing fastest, whether reads keep up with writes, which records nobody retrieves, and what to do about it.

The same data over the API

Everything the agent calls over the MCP is a plain HTTP endpoint, which is what makes refreshable artifacts possible. The refresh script the agent writes uses the API key from the environment and rewrites the page’s data blob:

curl -s https://api.latitude.so/v1/projects/$LATITUDE_PROJECT_SLUG/analytics/query \
  -H "Authorization: Bearer $LATITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": "traces",
    "metric": { "kind": "errorRate" },
    "breakdown": "model",
    "timeBucket": { "unit": "day" },
    "range": { "fromIso": "2026-08-31T00:00:00Z", "toIso": "2026-09-07T00:00:00Z" }
  }'

latitude analytics query --project-slug "$LATITUDE_PROJECT_SLUG" --format json --json '{
  "stream": "traces",
  "metric": { "kind": "errorRate" },
  "breakdown": "model",
  "timeBucket": { "unit": "day" },
  "range": { "fromIso": "2026-08-31T00:00:00Z", "toIso": "2026-09-07T00:00:00Z" }
}'

import { LatitudeClient } from "@latitude-data/sdk"

const client = new LatitudeClient({ apiKey: process.env.LATITUDE_API_KEY! })

const { series } = await client.analytics.query(process.env.LATITUDE_PROJECT_SLUG!, {
  body: {
    stream: "traces",
    metric: { kind: "errorRate" },
    breakdown: "model",
    timeBucket: { unit: "day" },
    range: { fromIso: "2026-08-31T00:00:00Z", toIso: "2026-09-07T00:00:00Z" },
  },
})

import json, os, urllib.request

req = urllib.request.Request(
    f"https://api.latitude.so/v1/projects/{os.environ['LATITUDE_PROJECT_SLUG']}/analytics/query",
    data=json.dumps({
        "stream": "traces",
        "metric": {"kind": "errorRate"},
        "breakdown": "model",
        "timeBucket": {"unit": "day"},
        "range": {"fromIso": "2026-08-31T00:00:00Z", "toIso": "2026-09-07T00:00:00Z"},
    }).encode(),
    headers={"Authorization": f"Bearer {os.environ['LATITUDE_API_KEY']}", "Content-Type": "application/json"},
)
with urllib.request.urlopen(req) as res:
    series = json.load(res)["series"]

Run the script by hand, from cron, from a GitHub Actions schedule that publishes the page, or from a scheduled agent run that also rewrites the findings. The latitude-artifacts skill ships working recipes for all of them.

Rendering and design

The skill renders every artifact from one template: the Latitude design tokens (Inter, the #0080FF primary, neutral surfaces, the same series palette the Latitude charts use), a light and a dark theme that follow your OS setting, KPI tiles with deltas, ECharts charts, tables with inline bars, and a findings section. Nothing is rendered by Latitude, which keeps the page portable: commit it to your repo, drop it in a shared folder, or publish it wherever you like. A good prompt without the skill is simply: “Build a self-contained HTML artifact of this project’s LLM reliability and cost over the last 30 days.” The agent discovers the right queryAnalytics calls on its own. The skill adds the intake questions, the data-source map, the shared theme and the refresh recipes.

Agent dispatch: the investigation counterpart, where an agent uses the same tools to root-cause a signal.
MCP, CLI, API and the SDKs it documents: the surfaces an artifact can be built from.
Skills: the full list of Latitude agent skills.

Overview

Getting Started

Observe

Understand

Refine

Security and Compliance

Deployment

Development

More

Overview

Three ways to build one

Example prompts

One-off reports

Refreshable dashboards

What the agent can query

The aggregate query: `queryAnalytics`

Row-level widgets

A worked example: memory

The same data over the API

Rendering and design

​Overview

​Three ways to build one

​Example prompts

​One-off reports

​Refreshable dashboards

​What the agent can query

​The aggregate query: queryAnalytics

​Row-level widgets

​A worked example: memory

​The same data over the API

​Rendering and design

​Related

Overview

Three ways to build one

Example prompts

One-off reports

Refreshable dashboards

What the agent can query

The aggregate query: `queryAnalytics`

Row-level widgets

A worked example: memory

The same data over the API

Rendering and design

Related