understudydocs

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. Use any JSON property names with string values. The complete JSON header value can be up to 16 KiB (16,384 UTF-8 bytes), with no separate entry-count or per-value limits. Details are in the header reference. Tags are optional: if the map is malformed or exceeds a constraint, the entire tag set is ignored and the request proceeds without tags. Tags stay within Understudy and are never forwarded to providers.

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.