For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

List runs for a simulation

Returns a paginated list of simulation runs.

GET /simulations/{simulation_id}/runs

Returns a paginated list of simulation runs. Use the query parameters to page through results.

Use the include parameter to include related entities in the response.

Path parameters

simulation_idstringrequired
Paddle ID of the simulation entity to work with.

Query parameters

idarray
Return only the IDs specified. Use a comma-separated list to get multiple entities.
afterstring
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
per_pageinteger
Default: 50

Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.

Default: 50; Maximum: 200.

Max: 200
includearray
Include related entities in the response.
Values
  • events
    Include an array of events related to this simulation run in the response.
order_bystring
Default: id[DESC]

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].

Valid fields for ordering: id.

Header parameters

Skip-Countstring
Set to true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.

Response (200)

dataarrayrequired
Single event run
Single event simulations play a single event.
idstringrequired
Example: ntfsimrun_01ghbkd0frb9k95cnhwd1bxpvk
Unique Paddle ID for this simulation run, prefixed with ntfsimrun_.
Pattern: ^ntfsimrun_[a-z\d]{26}$
statusstringrequired
Status of this simulation run.
Values
  • pending
    Simulation run is pending. Paddle is sending events that are part of this simulation.
  • completed
    Simulation run is completed. Paddle attempted to send events that are part of this simulation.
  • canceled
    Simulation run is canceled. Simulation run was canceled before all events were sent.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
typestringrequired
Single event sent for this simulation, in the format entity.event_type.
Values
+ Show all values
eventsarray
Events associated with this simulation run. Paddle creates a list of events for each simulation runs. Returned when the include parameter is used with the events value.
idstringrequired
Example: ntfsimevt_01hvg8ykjrcdr4jvv9rqcbkhfa
Unique Paddle ID for this simulation event, prefixed with ntfsimevt_.
Pattern: ^ntfsimevt_[a-z\d]{26}$
statusstringrequired
Status of this simulation run log.
Values
  • pending
    Simulation run log is pending. Paddle hasn't yet tried to deliver the simulated event.
  • success
    Simulation run log was successful. Paddle delivered the simulated event successfully.
  • failed
    Simulation run log failed. Paddle tried to deliver the simulated event, but it failed. If response object is null, no response received from your server. Check your notification setting endpoint configuration.
  • aborted
    Simulation run log aborted. Paddle could not attempt delivery of the simulated event.
event_typestringrequired
Type of event sent by Paddle, in the format entity.event_type.
Values
+ Show all values
payloadobjectrequired
Simulation payload. Pass a JSON object that matches the schema for an event type to simulate a custom payload. If omitted, Paddle populates with a demo example.
requestobject | nullrequired
Information about the request. Sent by Paddle as part of the simulation.
bodystringrequired
Request body sent by Paddle.
responseobject | nullrequired
Information about the response. Sent by the responding server for the notification setting.
bodystringrequired
Response body sent by the responding server. May be empty for success responses.
status_codenumberrequired
HTTP status code sent by the responding server.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
Scenario run
Scenario simulations play all events sent for a subscription lifecycle event.
idstringrequired
Example: ntfsimrun_01ghbkd0frb9k95cnhwd1bxpvk
Unique Paddle ID for this simulation run, prefixed with ntfsimrun_.
Pattern: ^ntfsimrun_[a-z\d]{26}$
statusstringrequired
Status of this simulation run.
Values
  • pending
    Simulation run is pending. Paddle is sending events that are part of this simulation.
  • completed
    Simulation run is completed. Paddle attempted to send events that are part of this simulation.
  • canceled
    Simulation run is canceled. Simulation run was canceled before all events were sent.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
typestringrequired
Scenario for this simulation. Scenario simulations play all events sent for a subscription lifecycle event.
Values
  • subscription_creation
    Simulates all events sent when a subscription is created.
  • subscription_renewal
    Simulates all events sent when a subscription is renewed.
  • subscription_pause
    Simulates all events sent when a subscription is paused.
  • subscription_resume
    Simulates all events sent when a subscription is resumed.
  • subscription_cancellation
    Simulates all events sent when a subscription is canceled.
eventsarray
Events associated with this simulation run. Paddle creates a list of events for each simulation runs. Returned when the include parameter is used with the events value.
idstringrequired
Example: ntfsimevt_01hvg8ykjrcdr4jvv9rqcbkhfa
Unique Paddle ID for this simulation event, prefixed with ntfsimevt_.
Pattern: ^ntfsimevt_[a-z\d]{26}$
statusstringrequired
Status of this simulation run log.
Values
  • pending
    Simulation run log is pending. Paddle hasn't yet tried to deliver the simulated event.
  • success
    Simulation run log was successful. Paddle delivered the simulated event successfully.
  • failed
    Simulation run log failed. Paddle tried to deliver the simulated event, but it failed. If response object is null, no response received from your server. Check your notification setting endpoint configuration.
  • aborted
    Simulation run log aborted. Paddle could not attempt delivery of the simulated event.
event_typestringrequired
Type of event sent by Paddle, in the format entity.event_type.
Values
+ Show all values
payloadobjectrequired
Simulation payload. Pass a JSON object that matches the schema for an event type to simulate a custom payload. If omitted, Paddle populates with a demo example.
requestobject | nullrequired
Information about the request. Sent by Paddle as part of the simulation.
bodystringrequired
Request body sent by Paddle.
responseobject | nullrequired
Information about the response. Sent by the responding server for the notification setting.
bodystringrequired
Response body sent by the responding server. May be empty for success responses.
status_codenumberrequired
HTTP status code sent by the responding server.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (uri)required
URL containing the query parameters of the original request, along with the after parameter that marks the starting point of the next page. Always returned, even if has_more is false.
has_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999

Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns 100001 to indicate that more than 100,000 entities match. Returns -1 when counting is skipped or couldn't be calculated.

Use has_more and next to page through all results rather than relying on estimated_total for an exact count.

Response
{
  "data": [
    {
      "id": "ntfsimrun_01j82gvz2cgw08p7mak3gcd3a3",
      "status": "completed",
      "type": "subscription_creation",
      "created_at": "2024-09-18T12:14:15.628606Z",
      "updated_at": "2024-09-18T12:14:27.244695Z"
    },
    {
      "id": "ntfsimrun_01j82gjx7fxdc27bsqxf311cbe",
      "status": "completed",
      "type": "subscription_creation",
      "created_at": "2024-09-18T12:09:18.831870Z",
      "updated_at": "2024-09-18T12:09:30.613445Z"
    }
  ],
  "meta": {
    "pagination": {
      "per_page": 50,
      "estimated_total": 2,
      "next": "https://api.paddle.dev/simulations/ntfsim_01j82d9tc19c67jds5vzbzjcns/runs?after=ntfsimrun_01j82gjx7fxdc27bsqxf311cbe",
      "has_more": false
    },
    "request_id": "12a52c1d-e899-4401-baf4-e836e3178062"
  }
}

Was this page helpful?