Feedback | Scout | Documentation

Feedback allows you to collect ratings and comments on outputs from your Scout workflows. Whether you’re gathering end-user reactions or enabling your team to review and triage outputs, feedback provides the insights you need to improve over time.

Feedback is currently available for workflows. Support for agents and other targets is coming soon.

Use Cases

External Feedback

Collect ratings from your end-users. Understand what’s working well and where improvements are needed.

Internal Review

Enable your team to review, triage, and track outputs. Assign issues, set priorities, and resolve problems systematically.

Collecting Feedback

To collect feedback, you’ll need:

Target ID

The specific output you want feedback on (e.g., a workflow run ID).

Scorer ID

Defines what type of feedback to collect (e.g., thumbs).

Metadata

Context about the feedback including user identification.

Create Thumbs Up Feedback

The thumbs scorer is Scout’s built-in scorer for simple thumbs up/down ratings. Use score: 1 for positive feedback and score: 0 for negative feedback.

1 const response = await fetch("https://api.scoutos.com/feedback", {
2   method: "POST",
3   headers: {
4     "Authorization": "Bearer YOUR_API_KEY",
5     "Content-Type": "application/json",
6   },
7   body: JSON.stringify({
8     target_type: "workflow_run",
9     target_id: "wfr_abc123",
10     scorer_id: "thumbs",
11     score: 1,
12     metadata: {
13       user_id: "user_456",
14       workflow_id: "wf_xyz",
15       session_id: "sess_789",
16     },
17   }),
18 });
19 
20 const feedback = await response.json();

Create Thumbs Down Feedback with Comment

1 const response = await fetch("https://api.scoutos.com/feedback", {
2   method: "POST",
3   headers: {
4     "Authorization": "Bearer YOUR_API_KEY",
5     "Content-Type": "application/json",
6   },
7   body: JSON.stringify({
8     target_type: "workflow_run",
9     target_id: "wfr_abc123",
10     scorer_id: "thumbs",
11     score: 0,
12     comment: "The response was not relevant to my question",
13     metadata: {
14       user_id: "user_456",
15       workflow_id: "wf_xyz",
16       session_id: "sess_789",
17     },
18   }),
19 });
20 
21 const feedback = await response.json();

Required Metadata

For workflow run targets, you must include workflow_id and session_id in metadata. The user_id field is optional but recommended for tracking feedback per user.

You can include additional context in metadata for segmentation (e.g., plan, region).

Copilot Feedback

The Scout Copilot component has built-in feedback UI. This section is for custom implementations using copilot authentication.

If you’ve built a custom copilot using the copilot API routes and authentication, use the copilot-specific feedback endpoint. This uses the same token as your copilot execution calls.

1 const copilotId = "cop_abc123";
2 
3 const response = await fetch(`https://api.scoutos.com/v2/copilots/${copilotId}/feedback`, {
4   method: "POST",
5   headers: {
6     "Authorization": `Bearer ${copilotToken}`, // Same token used for copilot execution
7     "Content-Type": "application/json",
8   },
9   body: JSON.stringify({
10     target_type: "workflow_run",
11     target_id: "wfr_abc123",
12     scorer_id: "thumbs",
13     score: 1,
14     metadata: {
15       user_id: "user_456",
16       workflow_id: "wf_xyz",
17       session_id: "sess_789",
18     },
19   }),
20 });
21 
22 const feedback = await response.json();

The request body format is identical to the standard feedback API. The only differences are:

Endpoint: /v2/copilots/{copilot_id}/feedback instead of /feedback
Authentication: Uses the copilot token instead of your API key

Managing Feedback Status

The status workflow helps you triage negative feedback that needs attention.

Status	Description
`new`	Just received, not yet triaged
`reviewing`	Team is investigating the issue
`resolved`	Issue was fixed (prompt updated, model tuned, etc.)
`dismissed`	Not actionable (user error, expected behavior, etc.)

Update feedback status to track review progress:

1 const response = await fetch("https://api.scoutos.com/feedback/fb_xyz789", {
2   method: "PATCH",
3   headers: {
4     "Authorization": "Bearer YOUR_API_KEY",
5     "Content-Type": "application/json",
6   },
7   body: JSON.stringify({
8     status: "reviewing",
9     assigned_to: "team_member_id",
10     internal_notes: "Investigating prompt template",
11   }),
12 });
13 
14 const updated = await response.json();

Filtering Feedback

List feedback with filters to analyze patterns:

1 const params = new URLSearchParams({
2   target_type: "workflow_run",
3   status: "new",
4   limit: "50",
5 });
6 
7 const response = await fetch(`https://api.scoutos.com/feedback?${params}`, {
8   headers: {
9     "Authorization": "Bearer YOUR_API_KEY",
10   },
11 });
12 
13 const { feedback } = await response.json();

Filter	Description
`target_type`	Filter by target type (e.g., `workflow_run`)
`target_id`	Filter by specific workflow run
`scorer_id`	Filter by scorer
`status`	Filter by status (e.g., `new`, `reviewing`)
`max_score`	Filter for negative feedback only (`max_score=0`)

Feedback Dashboard

View and manage all feedback from the Feedback page in Scout. The dashboard lets you view, filter, assign, and update feedback status with direct links to the workflow runs that generated each output.

Best Practices

Use consistent user IDs - Stable identifiers help you track feedback per user over time.
Encourage comments on negative feedback - Prompting for comments provides actionable insights.
Set up a review cadence - Regularly review new feedback to identify patterns.
Track resolution - Use the status workflow to ensure feedback leads to action.