Evaluations
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
GET | |
POST | |
GET | |
POST | |
GET | |
POST | |
POST | |
GET | |
PATCH | |
DELETE | |
GET | |
GET | |
GET | |
POST |
List all evaluations
Required API key scopes
evaluation:readQuery parameters
- directory_idstring
- directory_id__isnullboolean
- enabledboolean
- evaluation_typestringOne of:
"hog""llm_judge""sentiment" - id__inarray
- limitinteger
- offsetinteger
- order_byarray
- searchstring
Response
Example request
GET /api /projects /:project_id /evaluationsExample response
Status 200
Create evaluations
Required API key scopes
evaluation:writeRequest parameters
- namestring
- descriptionstring
- directory_idstring | null
- enabledboolean
- evaluation_type
- evaluation_config
- output_type
- output_configobject
- conditionsarray
- target
- target_configobject
- model_configuration
- deletedboolean
Response
Example request
POST /api /projects /:project_id /evaluationsExample response
Status 201
List all evaluations backfills
Historical runs of one evaluation over a closed time window (nested under an evaluation).
Required API key scopes
evaluation:readPath parameters
- evaluation_idstring
Query parameters
- limitinteger
- offsetinteger
Response
Example request
GET /api /projects /:project_id /evaluations /:evaluation_id /backfillsExample response
Status 200
Create evaluations backfills
Create a backfill: freeze the conditions, count the units, start the walk.
Required API key scopes
evaluation:writePath parameters
- evaluation_idstring
Request parameters
- window_startstring
- window_endstring
- conditionsarray
- rerun_existingbooleanDefault:
false
Response
Example request
POST /api /projects /:project_id /evaluations /:evaluation_id /backfillsExample response
Status 201
Retrieve evaluations backfills
Historical runs of one evaluation over a closed time window (nested under an evaluation).
Required API key scopes
evaluation:readPath parameters
- evaluation_idstring
- idstring
Response
Example request
GET /api /projects /:project_id /evaluations /:evaluation_id /backfills /:idExample response
Status 200
Create evaluations backfills cancel
Stop a running backfill. Evaluations already dispatched still finish.
Required API key scopes
evaluation:writePath parameters
- evaluation_idstring
- idstring
Response
Example request
POST /api /projects /:project_id /evaluations /:evaluation_id /backfills /:id /cancelExample response
Status 200
Create evaluations backfills estimate
Count what a backfill over the given window would evaluate, without creating one.
Required API key scopes
evaluation:readPath parameters
- evaluation_idstring
Request parameters
- window_startstring
- window_endstring
- conditionsarray
- rerun_existingbooleanDefault:
false
Response
Example request
POST /api /projects /:project_id /evaluations /:evaluation_id /backfills /estimateExample response
Status 200
Retrieve evaluations
Required API key scopes
evaluation:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /evaluations /:idExample response
Status 200
Update evaluations
Required API key scopes
evaluation:writePath parameters
- idstring
Request parameters
- namestring
- descriptionstring
- directory_idstring | null
- enabledboolean
- evaluation_type
- evaluation_config
- output_type
- output_configobject
- conditionsarray
- target
- target_configobject
- model_configuration
- deletedboolean
Response
Example request
PATCH /api /projects /:project_id /evaluations /:idExample response
Status 200
Delete evaluations
Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
Required API key scopes
evaluation:writePath parameters
- idstring
Example request
DELETE /api /projects /:project_id /evaluations /:idExample response
Status 405 No response body
Retrieve evaluations runs
One evaluation's latest graded runs in a period, newest first, optionally only the passed or failed ones.
Required API key scopes
evaluation:readPath parameters
- idstring
Query parameters
- date_fromstring
- date_tostring
- limitintegerDefault:
5 - outcomestringOne of:
"passed""failed" - refreshbooleanDefault:
false
Response
Example request
GET /api /projects /:project_id /evaluations /:id /runsExample response
Status 200
Status 400 The period is invalid, or an outcome filter is set on an evaluation without a passing rule.
Status 429 Too many queries are running for the project or organization.
Retrieve evaluations score distribution
How one numeric evaluation's scores in a period spread across its configured scale.
Required API key scopes
evaluation:readPath parameters
- idstring
Query parameters
- date_fromstring
- date_tostring
- refreshbooleanDefault:
false
Response
Example request
GET /api /projects /:project_id /evaluations /:id /score_distributionExample response
Status 200
Status 400 The period is invalid, or the evaluation is not numeric with a minimum and maximum score.
Status 429 Too many queries are running for the project or organization.
Retrieve evaluations overview
Each evaluation's results over a period, compared with the period of equal length before it.
Required API key scopes
evaluation:readQuery parameters
- date_fromstring
- date_tostring
- evaluation_idsarray
- refreshbooleanDefault:
false
Response
Example request
GET /api /projects /:project_id /evaluations /overviewExample response
Status 200
Status 400 The period is malformed, empty, longer than 91 days or out of range.
Status 429 Too many queries are running for the project or organization.
Create evaluations test hog
Test Hog evaluation code against sample events without saving.
Required API key scopes
evaluation:readRequest parameters
- output_typeDefault:
boolean - output_configobject
- sourcestring
- sample_countintegerDefault:
5 - allows_nabooleanDefault:
false - conditionsarray
- targetDefault:
generation - target_config
Response
Example request
POST /api /projects /:project_id /evaluations /test_hog




