Prompt attribution

Syncing gives every prompt an immutable version; attribution tells Moda which version served each production call. You attribute calls by stamping prompt identifiers on the data you already send — as event fields on the HTTP Ingestion API, as span attributes over OpenTelemetry, or as telemetry metadata with the Vercel AI SDK.

There is no SDK call that renders a prompt and attributes it automatically. Auto-instrumented OpenAI and Anthropic calls made through the Moda SDKs currently carry no prompt attribution — the SDKs expose no option to stamp these fields on auto-generated spans. Use one of the mechanisms on this page.

Where the identifiers come from

moda prompts sync writes .moda/prompts.lock.json with the registry IDs for every prompt:

.moda/prompts.lock.json

{
  "version": 1,
  "generatedAt": "2026-08-16T09:12:44.310Z",
  "prompts": {
    "support.triage": {
      "key": "support.triage",
      "sourcePath": "prompts/support/triage.prompt.md",
      "contentHash": "8c1f27ab…",
      "promptId": "prompt_7d1a9c0b3e5f24681357ace9",
      "versionId": "pver_0f31c2ab9d4e8877a1b2c3d4e5f60718"
    }
  }
}

Read the lockfile at startup (or bake the values in at build time) and stamp promptId and versionId on the calls that use that prompt.

Identifier fields

Purpose	`/v1/ingest` event field	OTLP span attribute	Vercel AI SDK metadata key
Prompt key	`prompt_name` (send the key)	`moda.prompt_key`	`moda.prompt_key`
Registry prompt ID (`prompt_…`)	`prompt_id`	`moda.prompt_id`	`moda.prompt_id`
Display name	`prompt_name`	`moda.prompt_name`	`moda.prompt_name`
Version string (human-readable)	`prompt_version`	`moda.prompt_version`	`moda.prompt_version`
Registry version ID (`pver_…`)	`prompt_version_id`	`moda.prompt_version_id`	`moda.prompt_version_id`

How much you send determines what you get:

Linking to a prompt requires prompt_id equal to the registry prompt ID, or prompt_name equal to the prompt key. On OTLP paths, moda.prompt_key alone is enough — the ID and name default to the key.
Per-version usage requires prompt_version_id. Without it, calls link to the prompt but not to a specific version.
prompt_version is a free-form display string (for example a semver or git SHA of your choosing); it defaults to the version ID when omitted.

Stamp the fields on the assistant events or LLM spans produced by the prompt.

HTTP Ingestion API

Set the prompt_* fields directly on /v1/ingest events:

curl -X POST https://moda-ingest.modas.workers.dev/v1/ingest \
  -H "Authorization: Bearer YOUR_MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "conversation_id": "conv_support_1042",
        "role": "user",
        "message": "My invoice is wrong",
        "timestamp": "2026-08-16T09:30:00Z"
      },
      {
        "conversation_id": "conv_support_1042",
        "role": "assistant",
        "message": "I can help with that. Let me pull up the invoice.",
        "model": "gpt-4o",
        "provider": "openai",
        "input_tokens": 412,
        "output_tokens": 58,
        "timestamp": "2026-08-16T09:30:02Z",
        "prompt_name": "support.triage",
        "prompt_id": "prompt_7d1a9c0b3e5f24681357ace9",
        "prompt_version_id": "pver_0f31c2ab9d4e8877a1b2c3d4e5f60718"
      }
    ]
  }'

Response

{ "success": true, "count": 2, "requestId": "d4f7c2a1-9b3e-4c58-a1f2-3e8b90c47d15" }

See HTTP API for the full event schema, batch limits, and error envelope.

OpenTelemetry span attributes

If you export OTLP traces to Moda from your own OpenTelemetry setup, set the moda.prompt_* attributes on each LLM span (see OpenTelemetry for exporter setup). Moda also reads gen_ai.prompt.name as a fallback for the prompt name. With the Moda SDK for Node.js, manual capture via withLLMCall exposes the underlying OTel span, so you can stamp the attributes there. Use this for calls the SDK does not auto-instrument:

app.ts

import { Moda, type Message } from 'moda-ai';
import { readFileSync } from 'node:fs';

await Moda.init(process.env.MODA_API_KEY!);

const lock = JSON.parse(readFileSync('.moda/prompts.lock.json', 'utf8'));
const triage = lock.prompts['support.triage'];

const messages: Message[] = [
  { role: 'system', content: 'Route urgent account issues before answering.' },
  { role: 'user', content: 'My invoice is wrong.' },
];

Moda.conversationId = 'conv_support_1042';

const data = await Moda.withLLMCall({ vendor: 'openai', type: 'chat' }, async ({ span }) => {
  span.rawSpan.setAttribute('moda.prompt_key', 'support.triage');
  span.rawSpan.setAttribute('moda.prompt_id', triage.promptId);
  span.rawSpan.setAttribute('moda.prompt_version_id', triage.versionId);
  span.reportRequest({ model: 'gpt-4o', messages });

  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ model: 'gpt-4o', messages }),
  });
  const result = await response.json();

  span.reportResponse({
    model: result.model,
    usage: result.usage,
    completions: result.choices,
  });
  return result;
});

console.log(data.choices[0]?.message?.content);
await Moda.flush();

withLLMCall is Node.js only. The Moda SDK for Python has no manual-capture equivalent; from Python, send attributed events through the HTTP API or set the attributes in your own OpenTelemetry instrumentation.

Vercel AI SDK

Pass the identifiers in the metadata of Moda.getVercelAITelemetry. The AI SDK forwards metadata keys as span attributes that Moda reads:

app.ts

import { Moda } from 'moda-ai';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { readFileSync } from 'node:fs';

await Moda.init(process.env.MODA_API_KEY!);

const lock = JSON.parse(readFileSync('.moda/prompts.lock.json', 'utf8'));
const triage = lock.prompts['support.triage'];

const userMessage = 'My invoice is wrong.';

Moda.conversationId = 'conv_support_1042';

const result = await generateText({
  model: openai('gpt-4o'),
  system: 'Route urgent account issues before answering.',
  prompt: userMessage,
  experimental_telemetry: Moda.getVercelAITelemetry({
    metadata: {
      'moda.prompt_key': 'support.triage',
      'moda.prompt_id': triage.promptId,
      'moda.prompt_version_id': triage.versionId,
    },
  }),
});

console.log(result.text);
await Moda.flush();

Moda.getVercelAITelemetry() snapshots the conversation and user context at the moment it is called. Set Moda.conversationId (or wrap the call in withConversationId) before creating the telemetry config, or the call is grouped without your conversation ID.

See Vercel AI SDK for the full integration, including streaming and tool calls.

What attribution unlocks

Runtime usage per version. The prompt detail page (Dashboard → Prompts → your prompt, Versions tab) shows calls, conversations, and input/output tokens grouped by version. Rows appear within minutes of ingestion.
Version-aware analysis. Attributed conversations let you compare how different versions behave in production and give prompt experiments a baseline tied to real versions.

Calls without prompt_version_id still count toward the prompt’s overall usage as long as they carry the prompt key or ID.

Next steps

Prompt workflow — where the lockfile and version IDs come from.
Prompt experiments — replay-based comparison of prompt versions.
HTTP API — full /v1/ingest event schema and limits.
OpenTelemetry — exporting OTLP traces to Moda from your own setup.

Get started

Concepts

Dashboard

Prompt management

Harness

Administration

Prompt attribution

Where the identifiers come from

Identifier fields

HTTP Ingestion API

OpenTelemetry span attributes

Vercel AI SDK

What attribution unlocks

Next steps

​Where the identifiers come from

​Identifier fields

​HTTP Ingestion API

​OpenTelemetry span attributes

​Vercel AI SDK

​What attribution unlocks

​Next steps

Where the identifiers come from

Identifier fields

HTTP Ingestion API

OpenTelemetry span attributes

Vercel AI SDK

What attribution unlocks

Next steps