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

List Simulation Runs

To list simulation runs, send a GET request to /v2/gen-ai/simulation_runs.

7 parameters
scenario_set_uuidstringoptional
Optional filter by scenario set.
pageintegeroptional
Page number.
per_pageintegeroptional
Items per page.
statusesarray<string>optional
Filter by one or more statuses. Empty means no status filter. - SIMULATION_RUN_STATUS_PENDING: Accepted and queued, not yet executing. - SIMULATION_RUN_STATUS_RUNNING: Episodes are executing. - SIMULATION_RUN_STATUS_SUCCEEDED: All episodes finished successfully. - SIMULATION_RUN_STATUS_FAILED: The run failed, for example because of a timeout or workflow error. - SIMULATION_RUN_STATUS_CANCELLED: The run was cancelled. - SIMULATION_RUN_STATUS_EVALUATING: Episodes finished and an attached evaluation is running. Only reachable when the create request included evaluation_config. When the evaluation reaches a terminal status, its outcome is reflected in the simulation run status. - SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL: The simulation or its attached evaluation completed with a mixture of successful and failed results.
searchstringoptional
Free-text search across the run name and scenario set name (case-insensitive substring match). Empty means no search.
sort_bystringoptional
Field to sort by. Defaults to creation date when unspecified. - SIMULATION_RUN_SORT_FIELD_CREATED_AT: Sort by creation date. Default. - SIMULATION_RUN_SORT_FIELD_NAME: Sort by customer-supplied run name (case-insensitive). - SIMULATION_RUN_SORT_FIELD_STATUS: Sort by status using lifecycle order (pending → running → terminal). - SIMULATION_RUN_SORT_FIELD_UPDATED_AT: Sort by last update date.
Allowed:SIMULATION_RUN_SORT_FIELD_UNSPECIFIEDSIMULATION_RUN_SORT_FIELD_CREATED_ATSIMULATION_RUN_SORT_FIELD_NAMESIMULATION_RUN_SORT_FIELD_STATUSSIMULATION_RUN_SORT_FIELD_UPDATED_ATDefault:SIMULATION_RUN_SORT_FIELD_UNSPECIFIED
sort_directionstringoptional
Sort direction. Defaults to descending 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.
linksobjectoptional
Links to other pages
metaobjectoptional
Meta information about the data set
simulation_runsarray<object>optional
The simulation runs for the current page.
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.