submit_feedback — Watt Data Docs

Submit structured feedback on data quality or tool results from a workflow session.

Quick Example

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "feedback_items": [
    {
      "feedback": "Demographic data appears outdated for entities in the 25-34 age range"
    }
  ]
}

Input Parameters

Parameter	Type	Required	Default	Constraints	Description
workflow_id	string	Yes	-	Valid UUID	Workflow ID for the feedback session
feedback_items	array	Yes	-	Min 1 item	Array of feedback items

feedback_items[].fields:

Field	Type	Required	Description
feedback	string	Yes	Specific feedback text
tool_trace_id	string	No	Trace ID from a previous tool call being referenced

Request Schema:

interface SubmitFeedbackParams {
  workflow_id: string;
  feedback_items: Array<{
    feedback: string;
    tool_trace_id?: string;
  }>;
}

Output Format

{
  workflow_id: string,
  feedback_id?: string,
  message: string,
  submitted_at: string,
  stored_items?: number,
  invalid_items?: number,
  warnings?: string[],
  tool_trace_id: string,
  // Debug mode only:
  debug?: boolean,
  tool?: string,
  items_received?: number
}

Response Fields:

Field	Type	Description
workflow_id	string	Workflow session identifier
feedback_id	string (optional)	Persisted feedback record ID; omitted when no row was stored
message	string	Human-readable submission summary
submitted_at	string	ISO 8601 timestamp of submission
stored_items	number (optional)	Count of items successfully persisted
invalid_items	number (optional)	Count of items rejected
warnings	string[] (optional)	Non-fatal warnings from submission
tool_trace_id	string	OpenTelemetry trace ID
debug	boolean (optional)	Debug mode only
tool	string (optional)	Debug mode only — tool name
items_received	number (optional)	Debug mode only — count of items passed in

Example Response:

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "feedback_id": "fb-a1b2c3d4",
  "message": "Feedback submitted successfully. 2 item(s) stored.",
  "submitted_at": "2025-01-16T12:00:00Z",
  "stored_items": 2,
  "tool_trace_id": "x9y8z7w6"
}

Error Handling

Common Errors:

Unauthenticated request: "Authentication required to submit feedback"
Missing validated workflow: "Workflow ID is required but was not validated"

When to Submit Feedback

After reviewing data that seems incorrect or outdated
When tool results don't match expectations
To report trait membership or demographic data issues
To flag specific entity profiles with questionable data

Usage Examples

Example 1: General feedback

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "feedback_items": [
    {
      "feedback": "Demographic data appears outdated for entities in the 25-34 age range"
    }
  ]
}

Example 2: Feedback with tool trace reference

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "feedback_items": [
    {
      "tool_trace_id": "a1b2c3d4e5f6",
      "feedback": "Trait membership seems incorrect - expected outdoor enthusiasts but got tech professionals"
    },
    {
      "feedback": "Missing key demographic fields in the results"
    }
  ]
}