Metadata

Every call is traced automatically, with no setup required. Grouping calls into a session, attributing them to a particular user, and similar views all build on top of that automatic trace, but they are not automatic themselves: each depends on a small piece of information, called metadata, being sent along with the call.

What metadata is

Metadata is a set of your own key-value pairs, attached to a call at the time it is made. Forgebench does not interpret most of what you send; it is recorded and made available for filtering exactly as sent. A small number of keys are treated specially, described below, because they drive a particular view in Forgebench rather than acting as a plain filter.

What is already attached, without you sending anything

Alongside anything you send yourself, Forgebench writes a further set of information onto every trace automatically. This part is not something you configure, and it cannot be altered or forged by a caller. It is what makes a trace trustworthy for questions of attribution and billing:

Sending metadata

Metadata is sent as a metadata.dimensions object alongside the rest of the call. Each entry in it becomes both a filter you can search on later and part of the permanent record of that call.

curl -X POST https://api.forgebench.ai/v1/chat/completions \
-H "Authorization: Bearer sk_..." \
-H "Content-Type: application/json" \
-d '{
  "model": "mock-gpt",
  "messages": [{"role": "user", "content": "Hello"}],
  "metadata": {
    "dimensions": {
      "feature": "checkout-assistant",
      "session": "conv_8f21",
      "customer": "acct_4471"
    }
  }
}'

from forgebench import Forgebench

client = Forgebench(api_key="sk_...", base_url="https://api.forgebench.ai")

resp = client.chat.completions.create(
  model="mock-gpt",
  messages=[{"role": "user", "content": "Hello"}],
  extra_body={
      "metadata": {
          "dimensions": {
              "feature": "checkout-assistant",
              "session": "conv_8f21",
              "customer": "acct_4471",
          }
      }
  },
)

import { Forgebench, type ChatCompletionRequest } from "@seedlinglabs/forgebench-sdk";

const forgebench = new Forgebench({ apiKey: "sk_...", baseUrl: "https://api.forgebench.ai" });

const res = await forgebench.chat.create({
model: "mock-gpt",
messages: [{ role: "user", content: "Hello" }],
metadata: {
  dimensions: {
    feature: "checkout-assistant",
    session: "conv_8f21",
    customer: "acct_4471",
  },
},
} as ChatCompletionRequest & Record<string, unknown>);

The two keys with special meaning

Any other key is your own choice, and is recorded as a plain, searchable filter, for example dimensions.customer in the example above. There is no fixed list of allowed keys beyond the two above.

Limits

Next