uip traces feedback

Syntax and options for `uip traces feedback`, which creates and manages LLM Observability feedback attached to a trace or span.

uip traces feedback manages LLM Observability feedback — a positive/negative rating, comment, and category tags attached to a trace or span. Use it to record human review of an agent's output, or to pull recorded feedback back out for reporting.

This page is part of the uip traces tool — see that page for spans get.

Synopsis

uip traces feedback create --trace-id <id> (--positive | --negative) --folder-key <guid> [--span-id <id>] [--comment <text> | --comment-file <path>] [--category <tag>...] [--agent-id <guid>] [--agent-version <str>]
uip traces feedback get <id> [--folder-key <guid>]
uip traces feedback list [--agent-id <guid>] [--agent-version <str>] [--trace-id <id>] [--span-id <id>] [--status <value>...] [--positive | --negative] [--limit <n>] [--offset <n>] [--folder-key <guid>]
uip traces feedback list detailed [--agent-id <guid>] [--agent-version <str>] [--trace-id <id>] [--span-id <id>] [--status <value>...] [--positive | --negative] [--category-id <guid>...] [--after <iso> | --since <duration>] [--before <iso>] [--sort-by <field>] [--sort-order <dir>] [--limit <n>] [--offset <n>] [--folder-key <guid>]
uip traces feedback update <id> (--positive | --negative) --folder-key <guid> [--comment <text> | --comment-file <path>] [--metadata <json> | --metadata-file <path>] [--category <tag>...]
uip traces feedback delete <id> --folder-key <guid> -y

All verbs honor the global options and the standard exit codes.

uip traces feedback create

Create feedback for a trace (or a specific span within it).

Options

Flag	Description
--trace-id <id>	Required. Trace ID (32-char hex or GUID).
--positive / --negative	Required — exactly one. Sentiment of the feedback.
--folder-key <guid>	Required. Orchestrator folder key.
--span-id <id>	Span ID. Defaults to the trace's root span when omitted.
--comment <text>	Free-text annotation (max 1,048,576 characters). Mutually exclusive with --comment-file.
--comment-file <path>	Read the comment from a file; pass - to read from stdin. Mutually exclusive with --comment.
--category <tag>	Category tag. Repeatable. The platform recognizes built-in tags like Output, Agent Error, and Agent Plan Execution, but any string is accepted.
--agent-id <guid>	Agent reference ID.
--agent-version <str>	Agent version (max 100 characters).

Example

uip traces feedback create \
  --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 \
  --positive \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

Data shape

{
  "Code": "FeedbackCreate",
  "Data": { "Id": "a1b2c3d4-0000-0000-0000-000000000002" }
}

Data is an unmodified pass-through of whatever the Feedback API returns — the CLI doesn't project it to a fixed field set, so the real response can carry more fields than shown here.

uip traces feedback get

Get a single feedback record by ID.

Arguments

• <id> (required) — Feedback record ID (GUID). Fails client-side with "Invalid feedback ID format" if it isn't a GUID.

Options

Flag	Description
--folder-key <guid>	Orchestrator folder key. The server generally requires this to authorize the read even though the CLI doesn't hard-fail without it client-side.

Example

uip traces feedback get a1b2c3d4-0000-0000-0000-000000000002 \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

Data shape

{
  "Code": "FeedbackGet",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000002",
    "IsPositive": true
  }
}

Like create, Data is a raw pass-through — the real response typically carries more fields (comment, metadata, categories, timestamps) than this minimal example shows.

uip traces feedback list

List feedback entries, filtered by trace, span, agent, status, or sentiment.

Options

Flag	Description
--agent-id <guid>	Filter by agent ID.
--agent-version <str>	Filter by agent version.
--trace-id <id>	Filter by trace ID.
--span-id <id>	Filter by span ID.
--status <value>	Filter by status: Pending, Approved, Dismissed. Repeatable.
--positive / --negative	Return only positive or only negative feedback. Mutually exclusive.
--limit <n>	Max results. Defaults to 20, capped at 100.
--offset <n>	Results to skip. Defaults to 0.
--folder-key <guid>	Orchestrator folder key.

Example

uip traces feedback list --trace-id 4bf92f3577b34da6a3ce929d0e0e4736

Data shape

{
  "Code": "FeedbackList",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000002",
      "IsPositive": true
    }
  ]
}

An empty result prints "No feedback found. Use 'uip traces feedback create' to add feedback."

uip traces feedback list detailed

List feedback with extended filters (time window, category, sort) and span context. This is a subcommand of list, not a top-level verb — the invocation is uip traces feedback list detailed, with the space, not list-detailed.

Options

Flag	Description
--agent-id <guid>	Filter by agent ID.
--agent-version <str>	Filter by agent version.
--trace-id <id>	Filter by trace ID.
--span-id <id>	Filter by span ID.
--status <value>	Filter by status: Pending, Approved, Dismissed. Repeatable.
--positive / --negative	Return only positive or only negative feedback. Mutually exclusive.
--category-id <guid>	Filter by category ID. Repeatable.
--after <iso>	Created after this ISO 8601 timestamp.
--before <iso>	Created before this ISO 8601 timestamp.
--since <duration>	Relative lookback shorthand for --after — for example 1h, 24h, 7d. Only h (hours) and d (days) units are accepted.
--sort-by <field>	Sort field: createdAt or updatedAt. Defaults to createdAt.
--sort-order <dir>	Sort direction: asc or desc. Defaults to desc.
--limit <n>	Max results. Defaults to 20, capped at 200 (higher than plain list's cap of 100).
--offset <n>	Results to skip. Defaults to 0.
--folder-key <guid>	Orchestrator folder key.

Note:

--since and --after both set the same underlying start-time filter — --since is evaluated relative to "now" at the moment the command runs.

Example

uip traces feedback list detailed --since 24h

Data shape

{
  "Code": "FeedbackListDetailed",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000002",
      "IsPositive": true,
      "TraceId": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  ]
}

The underlying API response is paginated ({ items, totalCount }), but the CLI only emits the items array as Data — the total match count (totalCount) is not surfaced. To know whether more results exist beyond --limit, compare the returned count to --limit rather than relying on a total.

uip traces feedback update

Update an existing feedback record's sentiment, comment, metadata, or categories.

Important:

The API replaces the whole record rather than patching it, so the CLI reads the existing record first and carries over any field you didn't pass — except --category: omitting it leaves existing categories untouched, but this read-then-write is not atomic. A concurrent edit landing between the read and the write is silently lost.

Arguments

• <id> (required) — Feedback record ID (GUID).

Options

Flag	Description
--positive / --negative	Required — exactly one. New sentiment.
--folder-key <guid>	Required. Orchestrator folder key.
--comment <text>	Updated comment (max 1,048,576 characters). Mutually exclusive with --comment-file. Omit to keep the existing comment.
--comment-file <path>	Read the updated comment from a file; pass - for stdin. Mutually exclusive with --comment.
--metadata <json>	Updated metadata; must be valid JSON (max 1,048,576 characters). Mutually exclusive with --metadata-file. Omit to keep the existing metadata.
--metadata-file <path>	Read updated metadata from a file; pass - for stdin. Mutually exclusive with --metadata.
--category <tag>	Replacement category tags. Repeatable. Omit entirely to leave existing categories as they are — passing it replaces the full set, it doesn't merge.

Examples

# change sentiment and add a comment
uip traces feedback update a1b2c3d4-0000-0000-0000-000000000002 \
  --negative \
  --comment "Wrong output" \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

# attach metadata read from a file
uip traces feedback update a1b2c3d4-0000-0000-0000-000000000002 \
  --positive \
  --metadata-file review.json \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

Data shape

{
  "Code": "FeedbackUpdate",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000002",
    "IsPositive": false
  }
}

uip traces feedback delete

Delete a feedback record by ID. This is a destructive operation — it requires -y, --yes; the CLI never prompts.

Arguments

• <id> (required) — Feedback record ID (GUID).

Options

Flag	Description
--folder-key <guid>	Required. Orchestrator folder key.
-y, --yes	Confirm this irreversible operation. Required — the CLI never prompts.

Example

uip traces feedback delete a1b2c3d4-0000-0000-0000-000000000002 \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001 \
  --yes

Data shape

{
  "Code": "FeedbackDelete",
  "Data": { "Id": "a1b2c3d4-0000-0000-0000-000000000002" }
}

Error behavior

• 401 from the Feedback API: Failure: "Not authenticated. Run 'uip auth login' first.".
• 403: Failure: "Insufficient permissions. Ensure you have Logs.View / Logs.Create / Logs.Delete on this folder.".
• 404: Failure naming the missing feedback ID.
• An id that isn't a GUID (get, update, delete): Failure: "Invalid feedback ID format: <id>", checked client-side before any network call.

Related

• uip traces spans get — source of the --trace-id/--span-id values used above.
• Tools (plugins) — install, update, uninstall the traces-tool package.
• uip login — session used to authenticate every verb on this page.

See also

• uip traces