guides

Tag requests

Projects and workloads are Understudy's dimensions; tags are yours. A flat key/value map on the request lands verbatim on the capture, so the slices you'll want at dataset-building time — tenant, release, experiment cohort — are recorded at request time.

Sending tags

per request

curl https://api.understudylabs.com/v1/chat/completions \
  -H "Authorization: Bearer $UNDERSTUDY_API_KEY" \
  -H 'x-understudy-tags: {"env":"prod","tenant":"acme","release":"2026.24"}' \
  -H "content-type: application/json" \
  -d '{"model":"glm-5.1","messages":[{"role":"user","content":"..."}]}'

Or as an SDK default header for values that are constant per process (environment, release), adding per-call tags only where they vary. Constraints — at most 16 entries, lowercase-and-hyphen keys, string values up to 256 bytes — are specified in the header reference; a malformed map is rejected with a 400 that names the offending key rather than being silently truncated.

What's worth tagging

env — keep production evidence separable from staging even when both share a workload.
tenant or customer-tier — fine-tuning datasets often need per-tenant inclusion/exclusion later.
release— when output quality shifts, the first question is "which prompt version?"
cohort — your own A/B dimensions, beyond the routing split Understudy already records.

Where tags surface

On each capture's detail view in the dashboard, and in the capture envelope's tags field for exports — which is where they earn their keep, as filter predicates when assembling eval sets and training data.