Add Feedback to Request

Add user feedback to a request to track quality and satisfaction. This endpoint allows you to mark requests as positive or negative, which can be used for filtering, analytics, and improving your LLM application.

Feedback ratings are boolean values: true for positive (thumbs up) and false for negative (thumbs down).

Path Parameters

requestId

string

required

The unique identifier of the request to add feedback to. This can be found in the Helicone-Id response header when making requests through Helicone.Example: req_abc123def456

Request Body

rating

boolean

required

The feedback rating to apply to the request.

true - Positive feedback (thumbs up)
false - Negative feedback (thumbs down)

Response

data

null

Returns null on success.

error

string | null

Error message if the request failed.

Examples

Add Positive Feedback

Mark a request as positive:

cURL

curl --request POST \
  --url https://api.helicone.ai/v1/request/req_abc123def456/feedback \
  --header 'Authorization: Bearer <HELICONE_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rating": true
}'

TypeScript

const requestId = 'req_abc123def456';

const response = await fetch(
  `https://api.helicone.ai/v1/request/${requestId}/feedback`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      rating: true
    })
  }
);

const result = await response.json();
console.log('Feedback added successfully');

Python

import os
import requests

request_id = "req_abc123def456"

response = requests.post(
    f"https://api.helicone.ai/v1/request/{request_id}/feedback",
    headers={
        "Authorization": f"Bearer {os.environ['HELICONE_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "rating": True
    }
)

result = response.json()
print("Feedback added successfully")

Add Negative Feedback

Mark a request as negative:

cURL

curl --request POST \
  --url https://api.helicone.ai/v1/request/req_abc123def456/feedback \
  --header 'Authorization: Bearer <HELICONE_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rating": false
}'

TypeScript

const requestId = 'req_abc123def456';

const response = await fetch(
  `https://api.helicone.ai/v1/request/${requestId}/feedback`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      rating: false
    })
  }
);

const result = await response.json();
console.log('Negative feedback recorded');

Use Cases

User Feedback Collection

Capture user feedback in your application:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://gateway.helicone.ai/v1',
  defaultHeaders: {
    'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`
  }
});

// Make a request and capture the request ID
const { data, response } = await client.chat.completions
  .create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Explain quantum computing' }]
  })
  .withResponse();

const requestId = response.headers.get('helicone-id');

// Display response to user
const assistantMessage = data.choices[0].message.content;
console.log('Response:', assistantMessage);

// Later, when user provides feedback (e.g., thumbs up/down button)
const userFeedback = true; // User clicked thumbs up

await fetch(
  `https://api.helicone.ai/v1/request/${requestId}/feedback`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ rating: userFeedback })
  }
);

Feedback-Based Analytics

Query requests filtered by feedback rating:

// Query all requests with positive feedback
const queryPositiveFeedback = async () => {
  const response = await fetch(
    'https://api.helicone.ai/v1/request/query',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        filter: {
          feedback: {
            rating: {
              equals: true
            }
          }
        },
        limit: 100
      })
    }
  );
  
  const result = await response.json();
  console.log(`Found ${result.data.length} requests with positive feedback`);
  return result.data;
};

// Query all requests with negative feedback
const queryNegativeFeedback = async () => {
  const response = await fetch(
    'https://api.helicone.ai/v1/request/query',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        filter: {
          feedback: {
            rating: {
              equals: false
            }
          }
        },
        limit: 100
      })
    }
  );
  
  const result = await response.json();
  console.log(`Found ${result.data.length} requests with negative feedback`);
  return result.data;
};

A/B Testing with Feedback

Track feedback across different prompt versions:

// Version A
const testPromptA = async () => {
  const { data, response } = await client.chat.completions
    .create(
      {
        model: 'gpt-4',
        messages: [{
          role: 'system',
          content: 'You are a helpful assistant.'
        }, {
          role: 'user',
          content: userQuery
        }]
      },
      {
        headers: {
          'Helicone-Property-Prompt-Version': 'A',
          'Helicone-Property-Experiment': 'prompt-test-1'
        }
      }
    )
    .withResponse();
  
  return {
    requestId: response.headers.get('helicone-id'),
    content: data.choices[0].message.content
  };
};

// Version B
const testPromptB = async () => {
  const { data, response } = await client.chat.completions
    .create(
      {
        model: 'gpt-4',
        messages: [{
          role: 'system',
          content: 'You are a concise assistant that provides brief answers.'
        }, {
          role: 'user',
          content: userQuery
        }]
      },
      {
        headers: {
          'Helicone-Property-Prompt-Version': 'B',
          'Helicone-Property-Experiment': 'prompt-test-1'
        }
      }
    )
    .withResponse();
  
  return {
    requestId: response.headers.get('helicone-id'),
    content: data.choices[0].message.content
  };
};

// Collect feedback and compare
const collectFeedback = async (requestId: string, userRating: boolean) => {
  await fetch(
    `https://api.helicone.ai/v1/request/${requestId}/feedback`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ rating: userRating })
    }
  );
};

Automated Feedback Based on Criteria

Automatically add feedback based on response characteristics:

const addAutomatedFeedback = async (requestId: string, responseData: any) => {
  // Example: Mark as negative if response is too short
  const responseText = responseData.choices[0].message.content;
  const isGoodResponse = responseText.length > 50 && 
                         !responseText.includes('[error]');
  
  await fetch(
    `https://api.helicone.ai/v1/request/${requestId}/feedback`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ rating: isGoodResponse })
    }
  );
};

Updating Feedback

You can update existing feedback by making another POST request to the same endpoint with a new rating value. The latest rating will override the previous one.

// Initial feedback
await fetch(
  `https://api.helicone.ai/v1/request/${requestId}/feedback`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ rating: true })
  }
);

// Update feedback later
await fetch(
  `https://api.helicone.ai/v1/request/${requestId}/feedback`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ rating: false })
  }
);

Get Request by ID

Retrieve request details including feedback

Query Requests

Query requests filtered by feedback rating

Add Scores

Add detailed evaluation scores instead of simple ratings

Add Properties

Add custom properties to requests

Best Practices

Capture Context: Use custom properties to tag requests before collecting feedback for better analysis
Track Changes: If users can change their feedback, consider logging the change history separately
Combine with Scores: Use feedback for quick user ratings and scores for detailed evaluation metrics
Filter by Feedback: Regularly review negatively rated requests to identify areas for improvement
A/B Testing: Use feedback to compare different prompt versions or model configurations

​Path Parameters

​Request Body

​Response

​Examples

​Add Positive Feedback

​Add Negative Feedback

​Use Cases

​User Feedback Collection

​Feedback-Based Analytics

​A/B Testing with Feedback

​Automated Feedback Based on Criteria

​Updating Feedback

​Related Endpoints

Get Request by ID

Query Requests

Add Scores

Add Properties

​Best Practices

Path Parameters

Request Body

Response

Examples

Add Positive Feedback

Add Negative Feedback

Use Cases

User Feedback Collection

Feedback-Based Analytics

A/B Testing with Feedback

Automated Feedback Based on Criteria

Updating Feedback

Related Endpoints

Best Practices