Skip to content

Retry optimization job

POST
/api/v1/org/{org}/ws/{workspace}/optimization/jobs/{job_id}/retry
job_id
required
Job Id
string format: uuid
org
required
Org

Organization slug

string

Organization slug

workspace
required
Workspace

Workspace slug

string

Workspace slug

Successful Response

OptimizationJobResponse

Optimization job detail returned by hosted optimization endpoints.

object
agent_name
Any of:
string
artifacts
Artifacts
object
key
additional properties
any
backend
required
Backend
string
Allowed value: gepa
cancel_requested_at
Any of:
string
capability
required
OptimizationCapabilitySnapshot

Resolved capability metadata persisted onto an optimization job.

object
artifact_id
Any of:
string
name
required
Name

Capability artifact name

string
runtime_digest
Any of:
string
version
required
Version

Resolved capability version

string
completed_at
Any of:
string
components
Components
Array<string>
Allowed values: instructions agent_prompt capability_prompt skill_descriptions skill_bodies
config
required
OptimizationJobConfig

Hosted GEPA adapter settings supported by the current SDK bridge.

object
batch_sampler
Any of:
string
cache_evaluation
Cache Evaluation

Enable GEPA evaluation-result caching

boolean
candidate_selection_strategy
Any of:
string
capture_traces
Capture Traces

Capture Dreadnode trajectories for GEPA reflection

boolean
default: true
concurrency
Concurrency

How many GEPA candidates to evaluate in parallel. Each concurrent candidate provisions its own TaskEnvironment sandbox(es), so raising this multiplies sandbox pressure by the candidate count.

integer
default: 1 >= 1
dataset_input_mapping
Any of:
Array<string>
display_progress_bar
Display Progress Bar

Enable GEPA progress bars in the runtime logs

boolean
frontier_type
Any of:
string
Allowed values: instance objective hybrid cartesian
include_errors
Include Errors

Include execution errors in reflected side info

boolean
default: true
include_outputs
Include Outputs

Include generated outputs in reflected side info

boolean
default: true
max_merge_invocations
Any of:
integer
max_metric_calls
Any of:
integer
>= 1
max_reflection_examples
Max Reflection Examples

Maximum examples to retain per reflective minibatch

integer
default: 10 >= 1
max_runtime_sec
Any of:
integer
>= 1
max_side_info_chars
Max Side Info Chars

Maximum characters retained for per-example side info

integer
default: 4000 >= 256
max_trials
Any of:
integer
>= 1
max_trials_without_improvement
Any of:
integer
>= 1
merge_val_overlap_floor
Any of:
integer
module_selector
Any of:
string
parallel_rows
Parallel Rows

For target_kind=‘capability_env’ only: how many dataset rows to score concurrently within a single candidate evaluation. Each parallel row holds its own TaskEnvironment sandbox. Ignored for target_kind=‘capability_agent’.

integer
default: 1 >= 1
perfect_score
Any of:
number
reflection_lm
Any of:
string
reflection_minibatch_size
Any of:
integer
>= 1
reflection_prompt_template
Any of:
string
seed
Seed

Deterministic optimization seed

integer
0
skip_perfect_score
Any of:
boolean
task_ref
Any of:
string
task_refs
Any of:
Array<string>
timeout_sec
Any of:
integer
> 0
track_best_outputs
Track Best Outputs

Track best outputs in the GEPA result payload

boolean
val_evaluation_policy
Any of:
string
val_task_refs
Any of:
Array<string>
created_at
required
Created At
string
created_by
Any of:
string
created_by_email
Any of:
string
dataset_ref
Any of:
DatasetRef

Stable reference to a versioned dataset artifact.

object
name
required
Name

Dataset artifact name

string
version
required
Version

Explicit dataset version

string
error
Any of:
string
id
required
Id
string
metrics
Metrics
object
key
additional properties
Array<object>
OptimizationMetricPoint

One optimization metric sample for charts and live updates.

object
step
Any of:
integer
timestamp
Any of:
string
value
required
Value
number
model
required
Model
string
name
Any of:
string
objective
Any of:
string
organization_id
required
Organization Id
string
project
Any of:
string
reward_recipe
required
RewardRecipe

Declarative reward recipe resolved inside the hosted optimizer runtime.

object
name
required
Name

Reward recipe name

string
Allowed values: contains_v1 exact_match_v1 row_reward_v1 trajectory_imitation_v1
params
Params

Recipe parameters consumed by the hosted runtime

object
key
additional properties
any
run_ref
Any of:
string
started_at
Any of:
string
status
required
Status
string
Allowed values: pending queued running completed failed cancelled
summary
OptimizationSummary

Normalized optimization outcome summary.

object
best_candidate
Any of:
object
key
additional properties
string
best_score
Any of:
number
best_scores
Best Scores

Best multi-objective scores, if any

object
key
additional properties
number
frontier_size
Frontier Size

Final Pareto frontier size

integer
0
metadata
Metadata

Backend-specific result metadata

object
key
additional properties
any
objective
Any of:
string
train_size
Train Size

Effective train-set size

integer
0
val_size
Val Size

Effective validation-set size

integer
0
tags
Tags
Array<string>
target_kind
required
Target Kind
string
Allowed values: capability_agent capability_env
task_refs
Any of:
Array<string>
val_dataset_ref
Any of:
DatasetRef

Stable reference to a versioned dataset artifact.

object
name
required
Name

Dataset artifact name

string
version
required
Version

Explicit dataset version

string
val_task_refs
Any of:
Array<string>
workspace_id
required
Workspace Id
string

Invalid request

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Authentication failed

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Access forbidden

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Not found

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Already exists

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Validation error

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Upgrade required

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Rate limited

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Internal server error

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Bad gateway

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Gateway timeout

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error