---
title: "Start Optimization Job"
method: POST
path: "/api/v1/jobs/gepa"
---

# Start Optimization Job

`POST /api/v1/jobs/gepa`

Start an async job to run GEPA optimization on an arbiter.
Uses annotated train/test predictions from ClickHouse to optimize the arbiter.
Runs in an isolated Modal Sandbox for clean cancellation support.

The hub_jobs row is created *before* the sandbox starts so that the
sandbox always has a row to update with logs and terminal state.

## Headers

- `authorization` string, nullable

## Cookies

- `modaic_session` string, nullable

## Request body

- GepaJobRequest
  - `arbiter_repo` string, required
  - `arbiter_revision` string
  - `push_branch` string
  - `push_tag` string, nullable
  - `gepa_kwargs` GepaKwargs
    - `auto` 'light' | 'medium' | 'heavy', nullable
    - `max_full_evals` integer, nullable
    - `max_metric_calls` integer, nullable
    - `reflection_minibatch_size` integer
    - `candidate_selection_strategy` 'pareto' | 'current_best'
    - `reflection_lm` LM
      - `model` string, required
      - `kwargs` object, nullable
    - `skip_perfect_score` boolean
    - `add_format_failure_as_feedback` boolean
    - `component_selector` 'round_robin' | 'all'
    - `use_merge` boolean
    - `max_merge_invocations` integer, nullable
    - `seed` integer, nullable
    - `gepa_kwargs` object, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/modaic-ai/apis/modaic-api.md) · [All operations](https://skmtc.net/modaic-ai/apis/modaic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/modaic-ai/modaic-api/revisions/43a90513ac59/schema)