Fetching human review comments via API and BTQL

Last updated: February 2, 2026

Summary

Goal: Fetch human review comments and scores from the UI using the API or BTQL.

Features: REST API logs fetch endpoints, BTQL queries, comments field on log events.

Applicable To

Plans: Any

Deployments: Braintrust Hosted (any version), Self-hosted (requires version 1.1.27+)

Configuration Steps

Step 1: Verify version (self-hosted only)

Human review comments in API responses require version 1.1.27 or later for self-hosted deployments.

Step 2: Fetch comments via REST API

Use the project logs fetch endpoint to retrieve comments left in the UI.

curl -X POST https://api.braintrust.dev/v1/project_logs/{project_id}/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Each log event includes a comments field containing human review feedback.

Step 3: Query comments using BTQL

Comments are part of the BTQL schema and can be queried directly.

SELECT id, input, output, comments 
FROM project_logs 
WHERE comments IS NOT NULL

Step 4: Fetch comments from datasets

Dataset fetch responses also include the comments field when records have human review feedback.

curl -X POST https://api.braintrust.dev/v1/dataset/{dataset_id}/fetch \
  -H "Authorization: Bearer YOUR_API_KEY"