DigitalOcean API (unofficial showcase)
POST/v2/gen-ai/simulation_runs

Create Simulation Run

To create a simulation run, send a POST request to /v2/gen-ai/simulation_runs. The scenario set must be ready. Judge and user simulator models are optional and use platform defaults when omitted. The run is returned in the pending state.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

9 body fields
agent_configobjectoptional
Configuration of the candidate agent under test for a simulation run.
evaluation_configobjectoptional
Optional configuration that opts a simulation run into an evaluation. When included on the create-run request, the platform reserves a model_evaluation_run linked to this simulation run and dispatches the evaluation automatically after the simulation finishes. The evaluation reuses the simulation run's judge_model_uuid.
exploration_budgetintegeroptional
Optional run-level episodes-per-scenario override. When set, overrides each scenario's exploration_budget.
judge_model_uuidstringoptional
Optional model override for the judge. Platform default when unset.
max_turnsintegeroptional
Optional run-level turn budget. When set, overrides each scenario's max_turns.
namestringoptional
Optional run name.
scenario_set_uuidstringoptional
UUID of the existing scenario set to execute. The set must be ready.
user_simulator_configobjectoptional
Optional user simulator model settings such as temperature and max_tokens.
user_simulator_model_uuidstringoptional
Optional model override for the user simulator. Platform default when unset.

6 status codes
200A successful response.
simulation_runobjectoptional
One execution of a scenario set against a candidate agent.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404The resource was not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned: Authentication failed due to invalid credentials. A 404 is returned: The resource was not found. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.