DigitalOcean API (unofficial showcase)
GET/v2/gen-ai/simulation_runs/{run_uuid}/episodes

List Simulation Episodes

To list the episodes within a simulation run, send a GET request to /v2/gen-ai/simulation_runs/{run_uuid}/episodes.

9 parameters
run_uuidstringrequired
UUID of the run whose episodes to list.
scenario_uuidstringoptional
Optional filter by scenario.
pageintegeroptional
Page number.
per_pageintegeroptional
Items per page.
statusesarray<string>optional
Filter by one or more statuses. Empty means no status filter. - SIMULATION_EPISODE_STATUS_RUNNING: The episode is executing and a trajectory is available to retrieve. - SIMULATION_EPISODE_STATUS_FINISHED: The episode reached a stop condition and produced a verdict. - SIMULATION_EPISODE_STATUS_FAILED: The episode failed because of a cancel, timeout, or error. - SIMULATION_EPISODE_STATUS_PREPARING: The episode is allocated but its trajectory is not available yet.
verdictsarray<string>optional
Filter by one or more verdicts. Empty means no verdict filter. - SIMULATION_EPISODE_VERDICT_SUCCESS: The candidate agent satisfied the scenario's stopping criteria. - SIMULATION_EPISODE_VERDICT_FAILURE: The candidate agent did not satisfy the stopping criteria. - SIMULATION_EPISODE_VERDICT_INCONCLUSIVE: No conclusive verdict (e.g. max_turns reached without the judge finishing).
searchstringoptional
Free-text search across scenario_uuid and session_id (case-insensitive substring match). Empty means no search.
sort_bystringoptional
Field to sort by. Defaults to scenario ordering when unspecified. - SIMULATION_EPISODE_SORT_FIELD_SCENARIO: Sort by scenario_uuid then episode_index. Default. - SIMULATION_EPISODE_SORT_FIELD_CREATED_AT: Sort by creation date. - SIMULATION_EPISODE_SORT_FIELD_STATUS: Sort by episode status using lifecycle order. - SIMULATION_EPISODE_SORT_FIELD_VERDICT: Sort by verdict (nulls last).
Allowed:SIMULATION_EPISODE_SORT_FIELD_UNSPECIFIEDSIMULATION_EPISODE_SORT_FIELD_SCENARIOSIMULATION_EPISODE_SORT_FIELD_CREATED_ATSIMULATION_EPISODE_SORT_FIELD_STATUSSIMULATION_EPISODE_SORT_FIELD_VERDICTDefault:SIMULATION_EPISODE_SORT_FIELD_UNSPECIFIED
sort_directionstringoptional
Sort direction. Defaults to ascending when unspecified.
Allowed:SORT_DIRECTION_UNSPECIFIEDSORT_DIRECTION_ASCSORT_DIRECTION_DESCDefault:SORT_DIRECTION_UNSPECIFIED

6 status codes
200A successful response.
available_sort_byarray<string>optional
Sort-by values available for this list request.
available_sort_directionsarray<string>optional
Sort-direction values available for this list request.
available_statusesarray<string>optional
Statuses available for filtering this list request.
available_verdictsarray<string>optional
Verdicts available for filtering this list request.
episodesarray<object>optional
The episodes for the current page.
linksobjectoptional
Links to other pages
metaobjectoptional
Meta information about the data set
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.