Skip to main content
Use the REST API to run experiments when you’re working outside the Python SDK — for example, from a CI pipeline, a cURL script, or a generated OpenAPI client. Event logging follows the same flow described in Tracing via API. This page covers the additional endpoints that wrap those events into an experiment run.
If you have already scored your outputs offline and just want to upload the results, see Sync Offline Evaluations for a focused walkthrough. Attach your scores as metrics on each session.
1

Fetch your dataset (optional)

If you’re using a HoneyHive dataset, retrieve it and its datapoints:If you manage test data externally, skip this step.
2

Create the experiment run

POST /v1/runs with an optional dataset_id. The project is scoped by your API key. Save the returned run_id.
3

Execute and log each datapoint

For each test case:
  1. POST /session/start with metadata.run_id, metadata.datapoint_id, and metadata.dataset_id set on the session.
  2. Run your application logic and log events using the strategies in Tracing via API. Set the same metadata.run_id, metadata.datapoint_id, and metadata.dataset_id on each event. Pass any client-side metrics on the relevant events.
  3. Collect the session_id returned in step 1.
4

Complete the run

PUT /v1/runs/{run_id} with status: "completed" and event_ids set to the list of session IDs collected in the previous step.
event_ids takes the root session event IDs (the session_id values from step 3), not child event IDs.