---
title: "List runs for a simulation"
method: GET
path: "/simulations/{simulation_id}/runs"
tags: ["Simulation runs"]
---

# List runs for a simulation

`GET /simulations/{simulation_id}/runs`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/simulations/{simulation_id}/runs`
- Auth: HTTP bearer

Returns a paginated list of simulation runs. Use the query parameters to [page through results](https://developer.paddle.com/api-reference/about/pagination).

Use the `include` parameter to [include related entities](https://developer.paddle.com/api-reference/about/include-entities) in the response.

## Path parameters

- `simulation_id` string, required

## Query parameters

- `id` string[]
- `after` string
- `per_page` integer
- `include` SimulationsRunIncludeEnum[]
- `order_by` string

## Headers

- `Skip-Count` string

## Response `200`

The request has succeeded.

- object
  - `data` SimulationRunIncludes[], required
    - union: Represents a simulation run entity.
      - SimulationRunSingleEventIncludesModel: Single event simulations play a single event.
        - `id` string, required: Unique Paddle ID for this simulation run, prefixed with `ntfsimrun_`.
        - `status` 'pending' | 'completed' | 'canceled', required: Status of this simulation run.
        - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
        - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
        - `type` 'address.created' | 'address.imported' | 'address.updated' | 'adjustment.created' | 'adjustment.updated' | 'api_key.created' | 'api_key.expired' | 'api_key.expiring' | 'api_key.revoked' | 'api_key.updated' | 'api_key_exposure.created' | 'business.created' | 'business.imported' | 'business.updated' | 'client_token.created' | 'client_token.revoked' | 'client_token.updated' | 'customer.created' | 'customer.imported' | 'customer.updated' | 'discount.created' | 'discount.imported' | 'discount.updated' | 'discount_group.created' | 'discount_group.updated' | 'payment_method.saved' | 'payment_method.deleted' | 'payout.created' | 'payout.paid' | 'price.created' | 'price.imported' | 'price.updated' | 'product.created' | 'product.imported' | 'product.updated' | 'report.created' | 'report.updated' | 'subscription.activated' | 'subscription.canceled' | 'subscription.created' | 'subscription.imported' | 'subscription.past_due' | 'subscription.paused' | 'subscription.resumed' | 'subscription.trialing' | 'subscription.updated' | 'transaction.billed' | 'transaction.canceled' | 'transaction.completed' | 'transaction.created' | 'transaction.paid' | 'transaction.past_due' | 'transaction.payment_failed' | 'transaction.ready' | 'transaction.revised' | 'transaction.updated', required: Type of event sent by Paddle, in the format `entity.event_type`.
        - `events` SimulationEvent[]: 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.
          - `id` string, required: Unique Paddle ID for this simulation event, prefixed with `ntfsimevt_`.
          - `status` 'pending' | 'success' | 'failed' | 'aborted', required: Status of this simulation run log.
          - `event_type` 'address.created' | 'address.imported' | 'address.updated' | 'adjustment.created' | 'adjustment.updated' | 'api_key.created' | 'api_key.expired' | 'api_key.expiring' | 'api_key.revoked' | 'api_key.updated' | 'api_key_exposure.created' | 'business.created' | 'business.imported' | 'business.updated' | 'client_token.created' | 'client_token.revoked' | 'client_token.updated' | 'customer.created' | 'customer.imported' | 'customer.updated' | 'discount.created' | 'discount.imported' | 'discount.updated' | 'discount_group.created' | 'discount_group.updated' | 'payment_method.saved' | 'payment_method.deleted' | 'payout.created' | 'payout.paid' | 'price.created' | 'price.imported' | 'price.updated' | 'product.created' | 'product.imported' | 'product.updated' | 'report.created' | 'report.updated' | 'subscription.activated' | 'subscription.canceled' | 'subscription.created' | 'subscription.imported' | 'subscription.past_due' | 'subscription.paused' | 'subscription.resumed' | 'subscription.trialing' | 'subscription.updated' | 'transaction.billed' | 'transaction.canceled' | 'transaction.completed' | 'transaction.created' | 'transaction.paid' | 'transaction.past_due' | 'transaction.payment_failed' | 'transaction.ready' | 'transaction.revised' | 'transaction.updated', required: Type of event sent by Paddle, in the format `entity.event_type`.
          - `payload` SimulationPayload, required: Simulation payload. A JSON object that matches the schema for an event type.
          - `request` SimulationEventRequest, required: Information about the request. Sent by Paddle as part of the simulation.
            - `body` string, required: Request body sent by Paddle.
          - `response` SimulationEventResponse, required: Information about the response. Sent by the responding server for the notification setting.
            - `body` string, required: Response body sent by the responding server. May be empty for success responses.
            - `status_code` number, required: HTTP status code sent by the responding server.
          - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
          - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
      - SimulationRunScenarioIncludesModel: Scenario simulations play all events sent for a subscription lifecycle event.
        - `id` string, required: Unique Paddle ID for this simulation run, prefixed with `ntfsimrun_`.
        - `status` 'pending' | 'completed' | 'canceled', required: Status of this simulation run.
        - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
        - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
        - `type` 'subscription_creation' | 'subscription_renewal' | 'subscription_pause' | 'subscription_resume' | 'subscription_cancellation', required: Scenario for a simulation.
        - `events` SimulationEvent[]: 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.
          - `id` string, required: Unique Paddle ID for this simulation event, prefixed with `ntfsimevt_`.
          - `status` 'pending' | 'success' | 'failed' | 'aborted', required: Status of this simulation run log.
          - `event_type` 'address.created' | 'address.imported' | 'address.updated' | 'adjustment.created' | 'adjustment.updated' | 'api_key.created' | 'api_key.expired' | 'api_key.expiring' | 'api_key.revoked' | 'api_key.updated' | 'api_key_exposure.created' | 'business.created' | 'business.imported' | 'business.updated' | 'client_token.created' | 'client_token.revoked' | 'client_token.updated' | 'customer.created' | 'customer.imported' | 'customer.updated' | 'discount.created' | 'discount.imported' | 'discount.updated' | 'discount_group.created' | 'discount_group.updated' | 'payment_method.saved' | 'payment_method.deleted' | 'payout.created' | 'payout.paid' | 'price.created' | 'price.imported' | 'price.updated' | 'product.created' | 'product.imported' | 'product.updated' | 'report.created' | 'report.updated' | 'subscription.activated' | 'subscription.canceled' | 'subscription.created' | 'subscription.imported' | 'subscription.past_due' | 'subscription.paused' | 'subscription.resumed' | 'subscription.trialing' | 'subscription.updated' | 'transaction.billed' | 'transaction.canceled' | 'transaction.completed' | 'transaction.created' | 'transaction.paid' | 'transaction.past_due' | 'transaction.payment_failed' | 'transaction.ready' | 'transaction.revised' | 'transaction.updated', required: Type of event sent by Paddle, in the format `entity.event_type`.
          - `payload` SimulationPayload, required: Simulation payload. A JSON object that matches the schema for an event type.
          - `request` SimulationEventRequest, required: Information about the request. Sent by Paddle as part of the simulation.
            - `body` string, required: Request body sent by Paddle.
          - `response` SimulationEventResponse, required: Information about the response. Sent by the responding server for the notification setting.
            - `body` string, required: Response body sent by the responding server. May be empty for success responses.
            - `status_code` number, required: HTTP status code sent by the responding server.
          - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
          - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
  - `meta` PaginatedMeta, required: Information about this response.
    - `request_id` string, required: Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
    - `pagination` Pagination, required: Keys used for working with paginated results.
      - `per_page` integer, required: Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
      - `next` string, 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_more` boolean, required: Whether this response has another page.
      - `estimated_total` integer: 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.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-07-09** (v1) `e1ac347eb3c5`: 2 info
  - api tag `Simulations` removed
  - added the new optional `header` request parameter `Skip-Count`
- **2026-02-02** (v1) `9ba8be0f2006`: 8 breaking, 1 warning, 5 info
  - added the new path request parameter `simulation_id`
  - added `#/components/schemas/SimulationRunSingleEventIncludesModel, #/components/schemas/SimulationRunScenarioIncludesModel` to the `data/items/` response property `oneOf` list for the response status `200`
  - the `data/items/` response's property type changed from `object` to no type for status `200`
  - the `error` response's property type changed from `object` to no type for status `default`
  - …10 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/simulations/:simulation_id/runs/get.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)