---
title: "List evaluators with filters"
method: POST
path: "/api/evaluators/list/"
tags: ["evaluators"]
---

# List evaluators with filters

`POST /api/evaluators/list/`

List evaluators using POST-for-filtering. The backend returns only the current draft/latest row for each evaluator and includes filter metadata for dashboard clients.

## Query parameters

- `page` integer
- `page_size` integer
- `sort_by` string

## Headers

- `Authorization` string, required

## Request body

- object
  - `filters` ApiEvaluatorsListPostRequestBodyContentApplicationJsonSchemaFilters — Filter criteria using the standard Respan filter format.
  - `is_exporting` boolean — Reserved for dashboard exports.

## Response `200`

Paginated filtered evaluator list.

- EvaluatorsListEvaluatorsResponse200
  - `count` integer, required — Number of resources returned on this page.
  - `next` string, nullable — URL for the next page, if any.
  - `previous` string, nullable — URL for the previous page, if any.
  - `current_filters` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaCurrentFilters — Normalized filters applied to this request.
  - `results` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItems[], required
    - `id` string, required — Stable evaluator ID shared by all versions.
    - `version_id` string — Unique ID for this evaluator version.
    - `version` integer — Version number. The first draft is version 0.
    - `is_read_only` boolean — Whether this version is committed and immutable.
    - `version_description` string — Commit message for this version.
    - `name` string, required
    - `evaluator_slug` string — Organization-scoped evaluator slug.
    - `type` 'llm' | 'human' | 'code', required
    - `score_value_type` 'numerical' | 'boolean' | 'percentage' | 'single_select' | 'multi_select' | 'text' | 'json' | 'comment' | 'categorical', required
    - `eval_class` 'keywordsai_custom_llm' | 'custom_code' — Optional pre-built evaluator template.
    - `description` string, nullable
    - `score_config` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsScoreConfig — Score configuration. For numerical/percentage scores, use `min_score` and `max_score`. For select scores, use `choices`.
      - `min_score` number, double
      - `max_score` number, double
      - `choices` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsScoreConfigChoicesItems[]
        - `name` string, required
        - `value` union, required
          - string
          - number, double
          - boolean
    - `passing_conditions` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsPassingConditions — Passing conditions in the standard Respan filter format.
    - `llm_config` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsLlmConfig — LLM grader configuration. The backend validates this against the selected evaluator form.
      - `model` string
      - `evaluator_definition` string — Prompt/template used by the LLM grader.
      - `scoring_rubric` string
      - `temperature` number, double
      - `max_tokens` integer
      - `top_p` number, double
      - `frequency_penalty` number, double
      - `presence_penalty` number, double
      - `stop` string[]
      - `response_format` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsLlmConfigResponseFormat
      - `tools` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsLlmConfigToolsItems[]
      - `tool_choice` unknown
      - `verbosity` string
    - `code_config` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsCodeConfig — Code grader configuration.
      - `eval_code_snippet` string — Python code defining `main(eval_inputs)`.
    - `configurations` object — Legacy user-facing configuration object. New clients should prefer `llm_config`, `code_config`, `score_config`, and `passing_conditions`.
    - `categorical_choices` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsCategoricalChoicesItems[], nullable
      - `name` string, required
      - `value` union, required
        - string
        - number, double
        - boolean
    - `starred` boolean
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `created_by` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsCreatedBy
      - `id` integer
      - `first_name` string
      - `last_name` string
      - `email` string, email
    - `updated_by` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsUpdatedBy
      - `id` integer
      - `first_name` string
      - `last_name` string
      - `email` string, email
    - `editor` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsEditor
      - `id` integer
      - `first_name` string
      - `last_name` string
      - `email` string, email
    - `tags` ApiEvaluatorsListPostResponsesContentApplicationJsonSchemaResultsItemsTagsItems[]
      - `id` integer
      - `name` string
      - `color` string
    - `is_public` boolean — Whether this is a Respan-managed public evaluator.
    - `version_count` integer
  - `filters_data` object — Available filter options for evaluator list UI clients.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized - Missing or invalid authentication

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)