---
title: "Rank trainable models for a dataset + capability"
method: POST
path: "/api/finetuning-jobs/recommend/"
tags: ["finetuning-jobs"]
---

# Rank trainable models for a dataset + capability

`POST /api/finetuning-jobs/recommend/`

## Request

- Base URL: `https://api.overmindlab.ai`
- URL: `https://api.overmindlab.ai/api/finetuning-jobs/recommend/`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`
  - API key in cookie `sessionid`
  - API key in header `X-Api-Key`
  - HTTP bearer

Rank the trainable catalog for this dataset, with the benchmark evidence
behind each grade and the reason every excluded model was dropped.

## Request body

- FinetuningRecommendRequestRequest
  - `dataset_id` string, uuid, required
  - `capability_id` string, uuid, nullable
  - `eval_dataset_id` string, uuid, nullable

## Response `200`

- FinetuningRecommendationResponse
  - `task_type` string, required
  - `task_type_source` 'capability' | 'semantic' | 'heuristic' | 'declared_contract' | 'unknown', required: * `capability` - capability * `semantic` - semantic * `heuristic` - heuristic * `declared_contract` - declared_contract * `unknown` - unknown
  - `capability_context` object, nullable, required
  - `skill_weights` object, required
  - `dataset` FinetuningRecommendationDataset, required
    - `rows` integer, required
    - `total_tokens` integer, required
    - `max_token_length` integer, required
    - `has_tool_calling` boolean, required
  - `candidates` FinetuningExperiment[], required
    - `tier` string, required
    - `model` string, required
    - `display_name` string, required
    - `params` string, required
    - `total_params_b` number, double
    - `context_length_sft` integer, nullable
    - `max_batch_size` integer, nullable
    - `min_batch_size` integer, nullable
    - `match` number, double, nullable, required
    - `match_rank` integer, nullable, required
    - `match_pool` integer, required
    - `grade` number, double, nullable, required
    - `adjusted_grade` number, double, nullable, required
    - `lower_bound` number, double, nullable, required
    - `confidence` 'high' | 'medium' | 'low' | 'none', required: * `high` - high * `medium` - medium * `low` - low * `none` - none
    - `n_benchmarks` integer, required
    - `skill_scores` FinetuningSkillScore[], required
      - `skill` string, required
      - `weight` number, double, required
      - `percentile_in_field` number, double, required
      - `rank_in_field` integer, required
      - `field_n` integer, required
      - `percentile_global` number, double, required
    - `evidence` FinetuningEvidence[], required
      - `benchmark` string, required
      - `skill` string, required
      - `percentile` number, double, required
      - `cohort_n` integer, required
      - `source` string, required
      - `url` string, required
      - `provenance` 'measured' | 'lab_claimed', required: * `measured` - measured * `lab_claimed` - lab_claimed
    - `selected` boolean, required
    - `hyperparams` unknown, required
    - `use_lora` boolean, required
    - `training_type` FinetuningCatalogTrainingType: models.json ``finetuning.training_type`` — which FT methods are allowed.
      - `lora` FinetuningTrainingMethod, required
        - `enabled` boolean, required
        - `context_length` integer, nullable
        - `validated_context_length` boolean
      - `full` FinetuningTrainingMethod, required
        - `enabled` boolean, required
        - `context_length` integer, nullable
        - `validated_context_length` boolean
    - `gpu_config` FinetuningGpuConfig, required
      - `gpu_type` string, nullable, required
      - `num_gpus` integer, required
      - `max_model_len` integer, nullable, required
    - `cost_estimate` FinetuningCostEstimate, required
      - `usd` number, double, required
      - `price_per_million_usd` number, double, nullable, required
      - `trained_tokens` integer, required
      - `minimum_applied` boolean, required
    - `time_estimate` FinetuningTimeEstimate, required
      - `seconds` integer, nullable, required
      - `human` string, required
    - `learning_rate_lora` number, double, required
    - `learning_rate_full` number, double, required
    - `hyperparam_reasons` unknown, required
    - `serving_context` ServingContextPlan
      - `input_tokens` integer, required
      - `output_tokens` integer, required
      - `rows` integer, required
      - `required_context` integer, required
      - `max_model_len` integer, required
      - `model_context_limit` integer, required
      - `estimated` boolean, required
      - `warnings` string[]
  - `excluded` FinetuningExcludedModel[], required
    - `model` string, required
    - `reason` string, required
  - `shown` string[], required
  - `benchmark_snapshot` FinetuningBenchmarkSnapshot, required: Which artifact the grades came from. Each evidence row carries its own benchmark reference, so the snapshot only dates them.
    - `generated_at` string, nullable, required

---

[API](https://skmtc.dev/overmindlab/apis/overmind-api.md) - [All operations](https://skmtc.dev/overmindlab/apis/overmind-api/llms.txt) - [OpenAPI document](https://skmtc.dev/overmindlab/apis/overmind-api/revisions/0ecfd39e80c6?raw)