---
title: "Create Hosted Evaluation"
method: POST
path: "/api/v1/hosted-evaluations"
tags: ["hosted-evaluations"]
---

# Create Hosted Evaluation

`POST /api/v1/hosted-evaluations`

Create and start a hosted evaluation.

## Request body

- CreateHostedEvaluationRequest — Request to create and start a hosted evaluation
  - `environment_ids` string[], required — List of environment IDs to evaluate
  - `inference_model` string, required — Model ID for inference
  - `eval_config` HostedEvalConfig, required — Hosted evaluation configuration
    - `num_examples` integer, required — Number of examples to evaluate (-1 for all)
    - `rollouts_per_example` integer, required — Rollouts per example
    - `env_args` object, nullable — Optional environment arguments to pass to the evaluation
    - `allow_sandbox_access` boolean, nullable — Allow sandbox read/write access
    - `allow_instances_access` boolean, nullable — Allow instance creation and management access
    - `allow_tunnel_access` boolean, nullable — Allow tunnel creation and management access
    - `timeout_minutes` integer, nullable — Custom timeout in minutes for the hosted eval run. Defaults to 1440. Use any negative value for no sandbox lifetime deadline. Finite values must be between 60 and 5256000.
    - `custom_secrets` object, nullable — Custom secrets to set in the evaluation sandbox (e.g., API keys, tokens)
    - `sampling_args` object, nullable — Optional sampling arguments forwarded to `prime eval run --sampling-args`
    - `max_concurrent` integer, nullable — Optional max concurrency forwarded to `prime eval run --max-concurrent`
    - `auto_max_concurrent` boolean — Whether max_concurrent was computed from hosted eval runtime resources
    - `max_retries` integer, nullable — Optional max retries forwarded to `prime eval run --max-retries`
    - `state_columns` string[], nullable — Optional state columns forwarded to `prime eval run --state-columns`
    - `independent_scoring` boolean, nullable — Forward `--independent-scoring` to the hosted eval runner
    - `verbose` boolean, nullable — Forward `--verbose` to the hosted eval runner
    - `headers` string[], nullable — Optional repeated headers forwarded to `prime eval run --header`
    - `extra_env_kwargs` object, nullable — Optional environment constructor kwargs forwarded to `prime eval run --extra-env-kwargs`
    - `api_client_type` string, nullable — Optional API client type forwarded to `prime eval run --api-client-type`
    - `api_base_url` string, nullable — Optional inference base URL forwarded to `prime eval run --api-base-url`
    - `api_key_var` string, nullable — Optional API key env var forwarded to `prime eval run --api-key-var`
  - `team_id` string, nullable — Optional team ID to own the hosted evaluation
  - `name` string, nullable — Optional custom evaluation name

## Response `201`

Successful Response

- CreateHostedEvaluationResponse — Response after creating a hosted evaluation
  - `evaluation_id` string, required — ID of the created evaluation
  - `sandbox_id` string, nullable — ID of the sandbox running the evaluation
  - `status` string, required — Current status of the evaluation
  - `evaluation_ids` string[], nullable — List of evaluation IDs if multiple environments were provided
  - `error` string, nullable — Error message if creation failed

## Other responses

- `401` — Authorization failed
- `422` — Invalid request data

---

[API](https://skmtc.net/primeintellect/apis/pi-api.md) · [All operations](https://skmtc.net/primeintellect/apis/pi-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/primeintellect/pi-api/revisions/3d3868828a78/schema)