aimldocs
ReferenceApi

Evals

prompt-set suites graded against a model×endpoint matrix

List Eval Suites

GET
/v1/evals/suites

Authorization

bearer
AuthorizationBearer <token>

In: header

Query Parameters

cursor?string
limit?integer
Rangevalue <= 200

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/evals/suites"
{  "object": "list",  "data": [],  "next_cursor": ""}

Create Eval Suite

POST
/v1/evals/suites

Authorization

bearer
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/evals/suites" \  -H "Content-Type: application/json" \  -d '{    "name": "quality",    "cases": [      {        "id": "c1",        "input": {          "model": "openai/gpt-5-mini"        },        "grader": {          "kind": "exact",          "expected": "yes"        }      }    ]  }'
{  "id": "es_01J9ZK2K4Q7Q3M3QX1V0EVSU1",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0ORG1",  "name": "quality",  "cases": [    {      "id": "c1",      "input": {        "model": "openai/gpt-5-mini"      },      "grader": {        "kind": "exact",        "expected": "yes"      }    }  ],  "created_at": "2026-09-14T12:00:00Z",  "updated_at": "2026-09-14T12:00:00Z"}

Get Eval Suite

GET
/v1/evals/suites/{id}

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/evals/suites/string"
{  "id": "es_01J9ZK2K4Q7Q3M3QX1V0EVSU1",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0ORG1",  "name": "quality",  "cases": [    {      "id": "c1",      "input": {        "model": "openai/gpt-5-mini"      },      "grader": {        "kind": "exact",        "expected": "yes"      }    }  ],  "created_at": "2026-09-14T12:00:00Z",  "updated_at": "2026-09-14T12:00:00Z"}

Update Eval Suite

PATCH
/v1/evals/suites/{id}

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X PATCH "https://example.com/v1/evals/suites/string" \  -H "Content-Type: application/json" \  -d '{    "name": "quality",    "cases": [      {        "id": "c1",        "input": {          "model": "openai/gpt-5-mini"        },        "grader": {          "kind": "exact",          "expected": "yes"        }      }    ]  }'
{  "id": "es_01J9ZK2K4Q7Q3M3QX1V0EVSU1",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0ORG1",  "name": "quality",  "cases": [    {      "id": "c1",      "input": {        "model": "openai/gpt-5-mini"      },      "grader": {        "kind": "exact",        "expected": "yes"      }    }  ],  "created_at": "2026-09-14T12:00:00Z",  "updated_at": "2026-09-14T12:00:00Z"}

Delete Eval Suite

DELETE
/v1/evals/suites/{id}

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

curl -X DELETE "https://example.com/v1/evals/suites/string"
Empty

List Eval Runs

GET
/v1/evals/runs

Authorization

bearer
AuthorizationBearer <token>

In: header

Query Parameters

cursor?string
suite_id?string
limit?integer
Rangevalue <= 200

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/evals/runs"
{  "object": "list",  "data": [],  "next_cursor": ""}

Create Eval Run

POST
/v1/evals/runs

Authorization

bearer
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/evals/runs" \  -H "Content-Type: application/json" \  -d '{    "suite_id": "es_01J9ZK2K4Q7Q3M3QX1V0EVSU1",    "targets": [      {        "model": "openai/gpt-5-mini",        "endpoint": "ep_a"      }    ],    "budget_micro": 1000000  }'
{  "run": {    "id": "er_01J9ZK2K4Q7Q3M3QX1V0EVRU1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0ORG1",    "suite_id": "es_01J9ZK2K4Q7Q3M3QX1V0EVSU1",    "targets": [      {        "model": "openai/gpt-5-mini",        "endpoint": "ep_a"      }    ],    "budget_micro": 1000000,    "status": "pending",    "cost_micro": 0,    "created_at": "2026-09-14T12:00:00Z"  },  "estimate_micro": 4000}

Get Eval Run

GET
/v1/evals/runs/{id}

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/evals/runs/string"
{  "id": "er_01J9ZK2K4Q7Q3M3QX1V0EVRU1",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0ORG1",  "suite_id": "es_01J9ZK2K4Q7Q3M3QX1V0EVSU1",  "targets": [    {      "model": "openai/gpt-5-mini",      "endpoint": "ep_a"    }  ],  "budget_micro": 1000000,  "status": "pending",  "cost_micro": 0,  "created_at": "2026-09-14T12:00:00Z"}

List Eval Results

GET
/v1/evals/runs/{id}/results

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/evals/runs/string/results"
{  "object": "list",  "data": []}