---
title: "List scopes"
method: GET
path: "/scope"
tags: ["Scope"]
---

# List scopes

`GET /scope`

List scopes within an application.

## Query parameters

- `offset` integer
- `limit` integer
- `application_id` string, required
- `include_messages` boolean
- `status` 'pending_approval' | 'pending_hook' | 'pending_approval_denied' | 'pending' | 'creating' | 'active' | 'updating' | 'updating_approval' | 'deleting' | 'deleted' | 'failed' | 'stopping' | 'stopped' | 'cancelled'
- `type` 'custom' | 'web_pool' | 'web_pool_k8s' | 'serverless'
- `nrn` string
- `name` string
- `slug` string
- `dimensions` string
- `sort` string

## Response `200`

The list of scopes matching the query.

- ScopeListResponse
  - `paging` object, required
    - `total` integer, required — The total number of results matching the query.
    - `offset` integer, required — The starting point for pagination. Defaults to 0 if not provided.
    - `limit` integer, required — The maximum number of results to return per page. The maximum allowed value is 200.
  - `results` Scope[], required
    - `id` integer, required — A system-wide unique ID for the scope.
    - `name` string, required — The name of the scope.
    - `asset_name` string — The name of the asset.
    - `type` 'custom' | 'web_pool' | 'web_pool_k8s' | 'serverless', required — Defines the kind of scope you create. > ℹ️ **Note:** > > • **Agent-backed scopes:** Use `custom` to create a scope managed by your installed agent. > > • **Legacy scopes:** The other types are older, predefined scope types that depend on fixed infrastructure configurations.
    - `provider` 'your_provider_id' | 'GOOGLE:WEB_POOL:GKE' | 'AZURE:WEB_POOL:AKS' | 'OCI:WEB_POOL:OKE' | 'AWS:WEB_POOL:EKS' | 'AWS:WEB_POOL:EC2INSTANCES' | 'AWS:SERVERLESS:LAMBDA' — Identifies the provider that powers this scope. > ℹ️ **Note:** > > • **Agent-backed scopes:** The **UUID** of the scope specification you created. This UUID is returned when you define a new scope specification and acts as your provider ID. > > • **Legacy scopes:** One of the predefined provider strings.
    - `status` 'pending_approval' | 'pending_hook' | 'pending_approval_denied' | 'pending' | 'creating' | 'recreating' | 'active' | 'updating' | 'updating_approval' | 'deleting' | 'deleted' | 'failed' | 'stopping' | 'stopped' | 'cancelled', required — The status of the scope.
    - `slug` string, required — An application-wide unique slug for the scope.
    - `domain` string, required — An application-wide unique domain for the scope.
    - `application_id` integer, required — The ID of the application that owns this scope.
    - `requested_spec` ScopeRequestedSpec — Defines the technical specifications for this scope (will be replaced by capabilities).
      - `memory_in_gb` number — The amount of memory allocated to this scope, measured in gigabytes (GB).
      - `cpu_profile` 'standard' | 'intensive' — Defines the CPU profile for this scope.
      - `local_storage_in_gb` number — The amount of local storage available to this scope, measured in gigabytes (GB).
    - `capabilities` object — Defines optional features such as logging, auto scaling, and spot instances. See the [capabilities](/docs/scopes/capabilities) documentation for details.
    - `messages` object — Additional system messages related to the scope's status or configuration.
    - `tier` 'testing' | 'non_critical' | 'important' | 'critical' — Defines the tier type of the scope.
    - `external_created` boolean — Indicates whether the scope was provisioned externally. `false` when provisioned by nullplatform, `true` if created externally (e.g., via Terraform).
    - `tags` string[] — Tags associated with the scope.
    - `profiles` string[] — NRN profiles that must be applied to this scope, independent of runtime configurations.
    - `dimensions` object — Defines runtime configuration dimensions, such as environment or region, that apply to this scope.
    - `runtime_configurations` integer[] — Runtime configurations that apply to this scope based on its dimensions.
    - `domains` ScopeDomainResponse[] — Array of custom domains associated with this scope. > It returns an empty array if no custom domains are assigned to the scope.
      - `id` string, required — The application-wide unique ID for the custom domain.
      - `name` string, required — The name of the custom domain.
      - `type` string, required — The type of the domain.
      - `selector` object — The selector for the custom domain.
        - `organization_id` string — The organization ID.
        - `nrn` string — The NRN of entity.
        - `scope_id` string — The scope ID that the custom domains is associated with..
      - `status` 'active' | 'pending' — The status of the domain.
      - `created_at` string, date-time — The ISO-8601 UTC timestamp of when the custom domain was created.
      - `updated_at` string, date-time — The ISO-8601 UTC timestamp of when the custom domain was last updated.
    - `instance_id` string — A unique identifier for the runtime instance associated with this scope.
    - `application_name` string — The name of the application that owns this scope.
    - `active_deployment` object, nullable — The last finalized deployment for this scope, or `null` if no deployment has been completed.
    - `current_active_deployment` object, nullable — The currently running deployment for this scope.
    - `in_progress_deployment` object, nullable — A new deployment currently in progress, or `null` if none.
    - `stops_at` string, date-time, nullable — The ISO-8601 UTC timestamp when this scope is scheduled to stop, or `null` if not scheduled.
    - `token_for_links` string — A JWT token for generating authenticated scope links. Only present for organizations with `generate_domain_token` enabled.
    - `created_at` string, date-time — The ISO-8601 UTC timestamp of when the scope was created.
    - `updated_at` string, date-time — The ISO-8601 UTC timestamp of when the scope was last updated.
    - `metadata` MetadataComponent — The metadata loaded via the metadata catalog API.
      - `key` string — The key of the metadata.
      - `value` string — The value of the metadata.
      - `additional_properties` object — Additional metadata properties, including schemas and tags.
        - `schemas` object[] — The JSON schemas of the metadata.
        - `tags` object[] — Tags associated with the metadata.
          - `key` string
          - `value` string

## Other responses

- `4XX` — Client error responses due to invalid input or missing parameters.
- `5XX` — Server error responses indicating an issue on the API side.

---

[API](https://skmtc.dev/nullplatform/apis/nullplatform-api.md) · [All operations](https://skmtc.dev/nullplatform/apis/nullplatform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nullplatform/nullplatform-api/revisions/1c4ea154b159/schema)