> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Experiments via API

> Run HoneyHive experiments through the REST API from TypeScript, Go, or CI pipelines when you need custom orchestration outside the Python evaluate() SDK.

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](/v2/sdk-reference/openapi-sdks).

Event logging follows the same flow described in [Tracing via API](/v2/tracing/manual-instrumentation). This page covers the additional endpoints that wrap those events into an experiment run.

<Tip>
  If you have already scored your outputs offline and just want to upload the results, see [Sync Offline Evaluations](/v2/evaluation/sync-offline-results) for a focused walkthrough. Attach your scores as `metrics` on each session.
</Tip>

<Steps>
  <Step title="Fetch your dataset (optional)">
    If you're using a HoneyHive dataset, retrieve it and its datapoints:

    * [`GET /datasets`](/v2/api-reference-autogen/datasets/get-datasets) to find your dataset
    * [`GET /datapoints`](/v2/api-reference-autogen/datapoints/retrieve-a-list-of-datapoints) with the `dataset_name` query parameter to fetch its datapoints

    If you manage test data externally, skip this step.
  </Step>

  <Step title="Create the experiment run">
    [`POST /v1/runs`](/v2/api-reference-autogen/experiments/create-a-new-evaluation-run) with an optional `dataset_id`. The project is scoped by your API key. Save the returned `run_id`.
  </Step>

  <Step title="Execute and log each datapoint">
    For each test case:

    1. [`POST /session/start`](/v2/api-reference-autogen/sessions/start-a-new-session) 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](/v2/tracing/manual-instrumentation). 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.
  </Step>

  <Step title="Complete the run">
    [`PUT /v1/runs/{run_id}`](/v2/api-reference-autogen/experiments/update-an-evaluation-run) with `status: "completed"` and `event_ids` set to the list of session IDs collected in the previous step.

    <Note>
      `event_ids` takes the root session event IDs (the `session_id` values from step 3), not child event IDs.
    </Note>
  </Step>
</Steps>