> ## 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 experiments using the REST API for non-Python runtimes, custom pipelines, or CI systems

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.

<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 /runs`](/v2/api-reference-autogen/experiments/create-a-new-evaluation-run) with an optional `dataset_id`. 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/session/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 /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>