Skip to main content

Trace Facets API

All endpoints verified working via curl. Document updated only after curl confirmation.

Base path: /api/v1/traces/facets. Read-only, team-scoped discovery endpoints that let a filter bar populate its tag/metadata pickers from whatever the team has actually tagged or annotated a trace with (via tags/metadata on POST /api/v1/traces), instead of a hardcoded list. Any team member can read (requireAnyAuth — session cookie or personal API key, no role gate). Both routes dedupe and sort their results alphabetically, capped at 200 values.

GET /api/v1/traces/facets​

Returns every distinct tag, every distinct metadata key, and every distinct resolved model seen on the team's llm spans. No query params. Returns empty arrays when the team has no traces (or none carry tags/metadata/model).

models is the resolved model actually called (e.g. gpt-4o-mini-2024-07-18), not a GatewayModel.publicName (e.g. gpt-4o-mini) — the same value an online-eval rule's filter.model is compared against.

curl -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  "$ACRUXCORE_BASE_URL/traces/facets"

Response (status 200) — from a team with two traces, one tagged ["prod", "nl"] with metadata {"env": "prod", "lang": "nl"} and an llm span resolved to gpt-4o-mini-2024-07-18, the other tagged ["staging"] with metadata {"env": "staging"} and a span resolved to claude-3-5-sonnet-20241022:

{
  "tags": ["nl", "prod", "staging"],
  "metadataKeys": ["env", "lang"],
  "models": ["claude-3-5-sonnet-20241022", "gpt-4o-mini-2024-07-18"]
}

Team-scoped: another team's tags/keys never appear in the response.

GET /api/v1/traces/facets/values​

Returns the distinct string values seen for one metadata key, across the team's traces — populates the value picker once a metadata-key filter has been chosen. key is a required query param.

The response has no key field — it echoes only values, not the key that was queried. A caller that expects the request's key reflected back in the body will not find it there.

curl -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  "$ACRUXCORE_BASE_URL/traces/facets/values?key=env"

Response (status 200) — for the same seed data as above (env set to prod on one trace, staging on the other):

{
  "values": ["prod", "staging"]
}

Team-scoped: another team's values for the same key never appear.

Error responses​

Missing key query param entirely (status 400) — Zod's default required-field message:

curl -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  "$ACRUXCORE_BASE_URL/traces/facets/values"
{ "error": { "code": "VALIDATION_ERROR", "message": "Required" } }

key present but blank (status 400) — a different validation failure with its own message, since the param exists but fails the schema's min(1):

curl -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  "$ACRUXCORE_BASE_URL/traces/facets/values?key="
{ "error": { "code": "VALIDATION_ERROR", "message": "key is required." } }

No Authorization header, on either route (status 401):

curl "$ACRUXCORE_BASE_URL/traces/facets"
{ "error": { "code": "UNAUTHORIZED", "message": "Authentication required." } }