# Create a new eval.
Source:
POST
/v1/evals
Select code samplecURL (shell:curl)
```js
const url = 'https://app.everruns.com/api/v1/evals';
const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: '{"description":"Regression suite for the support agent","model_override":"gpt-5.1","name":"Support agent regression","tags":["regression","nightly"],"target":{"agent_id":"example","harness_id":"example","harness_name":"example","max_iterations":1,"model_id":"example","system_prompt":"example","type":"session"}}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```sh
curl --request POST \
--url https://app.everruns.com/api/v1/evals \
--header 'Content-Type: application/json' \
--data '{ "description": "Regression suite for the support agent", "model_override": "gpt-5.1", "name": "Support agent regression", "tags": [ "regression", "nightly" ], "target": { "agent_id": "example", "harness_id": "example", "harness_name": "example", "max_iterations": 1, "model_id": "example", "system_prompt": "example", "type": "session" } }'
```
* Production APIapp.everruns.com/api/v1/evals
## Request Bodyrequired
Media typeapplication/json
Request to create a new eval
object
**description**
Human-readable description. Safe to render in user-facing messages.
string | null
##### Example
```plaintext
Regression suite for the support agent
```
**model\_override**
Default model override applied to runs of this eval.
string | null
##### Example
```plaintext
gpt-5.1
```
**name**
required
Human-readable name. Safe to render in user-facing messages.
string
##### Example
```plaintext
Support agent regression
```
**tags**
Free-form tags attached to this resource.
Array\ | null
##### Example
```json
[
"regression",
"nightly"
]
```
**target**
One of:
* object
One of:
* object
Session creation parameters (mirrors CreateSessionRequest).
object
**agent\_id**
Agent to work in this session.
string | null
**harness\_id**
Harness for the session. If omitted, org default harness is used.
string | null
**harness\_name**
Addressable harness name (alternative to harness\_id).
string | null
**max\_iterations**
Max LLM iterations per turn.
integer | null
**model\_id**
LLM model override.
string | null
**system\_prompt**
System prompt override (prepended to agent prompt).
string | null
**type**
required
string
Allowed values: session
* object
Reference to a deployed app.
object
**app\_id**
required
string
**type**
required
string
Allowed values: app
* object
Label-only target for externally-executed runs (e.g. imported from Mira).
Carries provider/model labels and opaque params instead of session setup: external runs are ingested already-complete, so everruns never builds a session from this. Mirrors a provider-agnostic `(provider, model)` pair.
object
**model**
required
string
**params**
**provider**
required
string
**type**
required
string
Allowed values: external
* null
Session creation parameters (mirrors CreateSessionRequest).
object
**agent\_id**
Agent to work in this session.
string | null
**harness\_id**
Harness for the session. If omitted, org default harness is used.
string | null
**harness\_name**
Addressable harness name (alternative to harness\_id).
string | null
**max\_iterations**
Max LLM iterations per turn.
integer | null
**model\_id**
LLM model override.
string | null
**system\_prompt**
System prompt override (prepended to agent prompt).
string | null
**type**
required
string
Allowed values: session
* object
Reference to a deployed app.
object
**app\_id**
required
string
**type**
required
string
Allowed values: app
* object
Label-only target for externally-executed runs (e.g. imported from Mira).
Carries provider/model labels and opaque params instead of session setup: external runs are ingested already-complete, so everruns never builds a session from this. Mirrors a provider-agnostic `(provider, model)` pair.
object
**model**
required
string
**params**
**provider**
required
string
**type**
required
string
Allowed values: external
* object
null
## Responses
### 201
Created
Media typeapplication/json
An eval: a named collection of test cases for an agent.
object
**archived\_at**
When the eval was archived, if archived.
string | null format: date-time
**case\_count**
Number of cases.
integer format: int64
**created\_at**
required
When the eval was created.
string format: date-time
**deleted\_at**
When the eval was deleted, if deleted.
string | null format: date-time
**description**
Optional description.
string | null
**id**
required
External identifier (eval\_<32-hex>). Shown as “id” in API.
string
**last\_run**
One of:
* object
Last run summary (if any).
object
**created\_at**
required
When the run was created.
string format: date-time
**id**
required
Eval run identifier.
string
**status**
required
Run lifecycle status.
string
Allowed values: pending running completed failed cancelled
**summary**
One of:
* object
Aggregate metrics, if the run has completed.
object
**avg\_latency\_ms**
required
Mean case latency in milliseconds.
integer format: int64
**avg\_score**
required
Mean score across cases, 0.0 to 1.0.
number format: double
**avg\_turns**
required
Mean agent turns per case.
number format: double
**errored**
required
Number of cases that errored.
integer format: int32
**failed**
required
Number of cases that failed.
integer format: int32
**pass\_rate**
required
Fraction of cases that passed, 0.0 to 1.0.
number format: double
**passed**
required
Number of cases that passed.
integer format: int32
**total**
required
Total number of cases in the run.
integer format: int32
**total\_input\_tokens**
required
Total input tokens across cases.
integer format: int64
**total\_output\_tokens**
required
Total output tokens across cases.
integer format: int64
* null
null
* null
Aggregate metrics, if the run has completed.
object
**avg\_latency\_ms**
required
Mean case latency in milliseconds.
integer format: int64
**avg\_score**
required
Mean score across cases, 0.0 to 1.0.
number format: double
**avg\_turns**
required
Mean agent turns per case.
number format: double
**errored**
required
Number of cases that errored.
integer format: int32
**failed**
required
Number of cases that failed.
integer format: int32
**pass\_rate**
required
Fraction of cases that passed, 0.0 to 1.0.
number format: double
**passed**
required
Number of cases that passed.
integer format: int32
**total**
required
Total number of cases in the run.
integer format: int32
**total\_input\_tokens**
required
Total input tokens across cases.
integer format: int64
**total\_output\_tokens**
required
Total output tokens across cases.
integer format: int64
* object
null
* null
null
**model\_override**
Optional default model override for runs.
string | null
**name**
required
Display name.
string
**status**
required
Lifecycle status.
string
Allowed values: active archived deleted
**tags**
Organization tags.
Array\
**target**
One of:
* object
One of:
* object
Session creation parameters (mirrors CreateSessionRequest).
object
**agent\_id**
Agent to work in this session.
string | null
**harness\_id**
Harness for the session. If omitted, org default harness is used.
string | null
**harness\_name**
Addressable harness name (alternative to harness\_id).
string | null
**max\_iterations**
Max LLM iterations per turn.
integer | null
**model\_id**
LLM model override.
string | null
**system\_prompt**
System prompt override (prepended to agent prompt).
string | null
**type**
required
string
Allowed values: session
* object
Reference to a deployed app.
object
**app\_id**
required
string
**type**
required
string
Allowed values: app
* object
Label-only target for externally-executed runs (e.g. imported from Mira).
Carries provider/model labels and opaque params instead of session setup: external runs are ingested already-complete, so everruns never builds a session from this. Mirrors a provider-agnostic `(provider, model)` pair.
object
**model**
required
string
**params**
**provider**
required
string
**type**
required
string
Allowed values: external
* null
Session creation parameters (mirrors CreateSessionRequest).
object
**agent\_id**
Agent to work in this session.
string | null
**harness\_id**
Harness for the session. If omitted, org default harness is used.
string | null
**harness\_name**
Addressable harness name (alternative to harness\_id).
string | null
**max\_iterations**
Max LLM iterations per turn.
integer | null
**model\_id**
LLM model override.
string | null
**system\_prompt**
System prompt override (prepended to agent prompt).
string | null
**type**
required
string
Allowed values: session
* object
Reference to a deployed app.
object
**app\_id**
required
string
**type**
required
string
Allowed values: app
* object
Label-only target for externally-executed runs (e.g. imported from Mira).
Carries provider/model labels and opaque params instead of session setup: external runs are ingested already-complete, so everruns never builds a session from this. Mirrors a provider-agnostic `(provider, model)` pair.
object
**model**
required
string
**params**
**provider**
required
string
**type**
required
string
Allowed values: external
* object
null
**updated\_at**
required
When the eval was last updated.
string format: date-time
##### Example
```json
{
"archived_at": "2026-01-15T10:30:00Z",
"case_count": 12,
"created_at": "2026-01-15T10:30:00Z",
"deleted_at": "2026-01-15T10:30:00Z",
"description": "Regression suite for the support agent",
"id": "eval_01933b5a000070008000000000000001",
"last_run": {
"created_at": "2026-01-15T10:30:00Z",
"status": "pending",
"summary": {
"avg_latency_ms": 8450,
"avg_score": 0.85,
"avg_turns": 3.2,
"errored": 1,
"failed": 2,
"pass_rate": 0.75,
"passed": 9,
"total": 12,
"total_input_tokens": 14400,
"total_output_tokens": 10200
}
},
"model_override": "gpt-5.1",
"name": "Support agent regression",
"status": "active",
"tags": [
"regression",
"nightly"
],
"target": {
"type": "session"
},
"updated_at": "2026-01-15T10:30:00Z"
}
```