---
title: "Create Run"
method: POST
path: "/api/evaluations/{evaluation_id}/runs"
tags: ["evaluations"]
---

# Create Run

`POST /api/evaluations/{evaluation_id}/runs`

## Request

- Base URL: `https://app.getdot.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://app.getdot.ai/api/evaluations/{evaluation_id}/runs`
- Auth: one of:
  - API key in header `X-API-KEY`
  - API key in cookie `Authorization`
  - OAuth 2 (password, token URL `/api/auth/token`)

## Path parameters

- `evaluation_id` string, required

## Request body

- EvaluationRunCreateRequest
  - `target` EvaluationTarget
    - `kind` 'production' | 'environment'
    - `environment_id` string, nullable
  - `questions` EvaluationRunQuestionRequest[], nullable: Optional run-only question snapshot. Omit to use the saved evaluation; supplied cases never edit it.
    - `concept_id` string, nullable
    - `concept_name` string, nullable
    - `question` string, required
    - `expected_answer` string, required
    - `answer_type` 'number' | 'currency' | 'percent' | 'count' | 'ratio' | 'date'
    - `unit` string, nullable
    - `tolerance_pct` number
    - `source` QuestionSource
      - `system` string, nullable
      - `workbook` string, nullable
      - `view` string, nullable
      - `dashboard_name` string, nullable
      - `dashboard_url` string, nullable
      - `dashboard_id` string, nullable
      - `tile_id` string, nullable
      - `look_id` string, nullable
      - `query_id` string, nullable
      - `method` 'tile_read' | 'reconstructed', nullable
      - `reconstruction_accepted` boolean, nullable
      - `compiled_sql` string, nullable
      - `filters` object
      - `question_filters` object, nullable
      - `extracted_at` string, nullable
      - `definition` string, nullable
      - `legacy_run_status` string, nullable
      - `legacy_run_id` string, nullable
    - `id` string, required
  - `idempotency_key` string, nullable: Same key and request returns the accepted run. Reusing a key with different input returns 409. Use a new key for a new CI attempt.
  - `expected_target_commit` string, nullable: Full Dot context Git commit required at submission. A mismatch returns 409 before execution; this is not the customer repository SHA.
  - `trigger` 'manual' | 'api' | 'cli'
  - `metadata` object

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/getdot/apis/dot-api-2.md) · [All operations](https://skmtc.dev/getdot/apis/dot-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/getdot/apis/dot-api-2/revisions/d26fe7163a7f?raw)