---
id: scope-list
title: "List scopes"
description: "List scopes within an application."
sidebar_label: "List scopes"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "get api-method"
info_path: docs/api/nullplatform-api
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List scopes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/scope"}
  context={"endpoint"}
>
  
</MethodEndpoint>



List scopes within an application.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","name":"offset","schema":{"type":"integer","minimum":0},"description":"The starting point for pagination. Defaults to 0 if not provided.","example":0},{"in":"query","name":"limit","schema":{"type":"integer"},"description":"The maximum number of results to return per page.","example":30},{"in":"query","name":"application_id","schema":{"type":"string"},"required":true,"description":"The ID of the application for the scopes being listed. Allows up to 10 comma-separated values.\"","example":"5678,1234"},{"name":"include_messages","in":"query","description":"Specifies whether it includes messages in the response.","example":true,"schema":{"type":"boolean"}},{"in":"query","name":"status","schema":{"type":"string","enum":["pending_approval","pending_hook","pending_approval_denied","pending","creating","active","updating","updating_approval","deleting","deleted","failed","stopping","stopped","cancelled"]},"required":false,"description":"Status of the scope."},{"in":"query","name":"type","schema":{"type":"string","enum":["custom","web_pool","web_pool_k8s","serverless"]},"required":false,"description":"Type of the scope."},{"in":"query","name":"nrn","schema":{"type":"string","maxLength":500},"required":false,"description":"Filters scopes matching or more specific than the provided NRN. When provided, scopes are listed across the org/account/namespace/application hierarchy instead of by `application_id`.","example":"organization=1:account=2:namespace=3"},{"in":"query","name":"name","schema":{"type":"string","maxLength":255},"required":false,"description":"Filters scopes by name.","example":"Billing API"},{"in":"query","name":"slug","schema":{"type":"string","maxLength":120},"required":false,"description":"Filters scopes by slug.","example":"billing-api"},{"in":"query","name":"dimensions","schema":{"type":"string","maxLength":1000},"required":false,"description":"Filters scopes by dimensions.","example":"environment:production,country:us"},{"in":"query","name":"sort","schema":{"type":"string","maxLength":255},"required":false,"description":"Sort field and direction, separated by a colon. Defaults to `created_at:desc`.","example":"created_at:desc"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of scopes matching the query.","content":{"application/json":{"schema":{"type":"object","required":["paging","results"],"properties":{"paging":{"required":["offset","limit","total"],"properties":{"total":{"type":"integer","description":"The total number of results matching the query.","example":30},"offset":{"type":"integer","minimum":0,"description":"The starting point for pagination. Defaults to 0 if not provided.","example":0},"limit":{"type":"integer","description":"The number of results returned per page. Defaults to 30.","example":30}}},"results":{"type":"array","items":{"type":"object","required":["id","name","type","slug","status","domain","application_id"],"properties":{"id":{"example":1234,"type":"integer","description":"A system-wide unique ID for the scope."},"name":{"example":"Billing API","type":"string","maxLength":100,"description":"The name of the scope."},"asset_name":{"type":"string","description":"The name of the asset.","example":"main-asset"},"type":{"example":"custom","type":"string","enum":["custom","web_pool","web_pool_k8s","serverless"],"description":"Defines the kind of scope you create.\n\n> ℹ️ **Note:**\n>\n> • **Agent-backed scopes:** Use `custom` to create a scope managed by your installed agent.\n>\n> • **Legacy scopes:** The other types are\n  older, predefined scope types that depend on fixed infrastructure configurations."},"provider":{"example":"9e84a5c3-6c2e-4f15-90b0-1c67fd37f6e8","default":"your_provider_id","type":"string","enum":["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"],"description":"Identifies the provider that powers this scope.\n\n> ℹ️ **Note:**\n> \n> • **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.\n>\n> • **Legacy scopes:** One of the predefined provider strings."},"status":{"example":"active","type":"string","description":"The status of the scope.","enum":["pending_approval","pending_hook","pending_approval_denied","pending","creating","recreating","active","updating","updating_approval","deleting","deleted","failed","stopping","stopped","cancelled"],"title":"ScopeStatus"},"slug":{"example":"billing-api","maxLength":60,"type":"string","description":"An application-wide unique slug for the scope."},"domain":{"example":"billing-api-prod.nullapps.io","maxLength":60,"type":"string","description":"An application-wide unique domain for the scope."},"application_id":{"example":2345,"type":"integer","description":"The ID of the application that owns this scope."},"requested_spec":{"example":{"memory_in_gb":2,"cpu_profile":"standard","local_storage_in_gb":8},"type":"object","description":"Defines the technical specifications for this scope (will be replaced by capabilities).","properties":{"memory_in_gb":{"type":"number","default":2,"example":2,"description":"The amount of memory allocated to this scope, measured in gigabytes (GB)."},"cpu_profile":{"type":"string","enum":["standard","intensive"],"example":"standard","description":"Defines the CPU profile for this scope."},"local_storage_in_gb":{"type":"number","default":2,"example":2,"description":"The amount of local storage available to this scope, measured in gigabytes (GB)."}},"title":"ScopeRequestedSpec"},"capabilities":{"type":"object","description":"Defines optional features such as logging, auto scaling, and spot instances. See the [capabilities](/docs/scopes/capabilities) documentation for details."},"messages":{"type":"object","description":"Additional system messages related to the scope's status or configuration.","example":null},"tier":{"example":"important","type":"string","description":"Defines the tier type of the scope.","enum":["testing","non_critical","important","critical"],"title":"ScopeTier"},"external_created":{"type":"boolean","description":"Indicates whether the scope was provisioned externally. `false` when provisioned by nullplatform, `true` if created externally (e.g., via Terraform)."},"tags":{"example":["requires_deployment","high_priority"],"type":"array","items":{"type":"string"},"description":"Tags associated with the scope."},"profiles":{"type":"array","items":{"type":"string"},"example":["environment_production"],"description":"NRN profiles that must be applied to this scope, independent of runtime configurations."},"dimensions":{"type":"object","example":{"environment":"production"},"description":"Defines runtime configuration dimensions, such as environment or region, that apply to this scope."},"runtime_configurations":{"type":"array","items":{"type":"integer"},"example":[1234,2345],"description":"Runtime configurations that apply to this scope based on its dimensions."},"domains":{"type":"array","description":"Array of custom domains associated with this scope.\n> It returns an empty array if no custom domains are assigned to the scope.\n","items":{"type":"object","required":["id","name","type"],"properties":{"id":{"type":"string","description":"The application-wide unique ID for the custom domain.","example":"e78a0d21-3c48-7421-81cd-203fe84b8e47"},"name":{"type":"string","description":"The name of the custom domain.","example":"api.crypto-inc.com"},"type":{"type":"string","description":"The type of the domain.","example":"scope"},"selector":{"type":"object","description":"The selector for the custom domain.","properties":{"organization_id":{"type":"string","description":"The organization ID.","example":"1"},"nrn":{"type":"string","description":"The NRN of entity.","example":"organization=1:account=2:namespace=3:application=4"},"scope_id":{"type":"string","description":"The scope ID that the custom domains is associated with..","example":"1234"}}},"status":{"type":"string","description":"The status of the domain.","enum":["active","pending"],"example":"active"},"created_at":{"type":"string","description":"The ISO-8601 UTC timestamp of when the custom domain was created.","format":"date-time","example":"2025-01-02T00:00:00Z"},"updated_at":{"type":"string","description":"The ISO-8601 UTC timestamp of when the custom domain was last updated.","format":"date-time","example":"2025-02-02T00:00:00Z"}},"title":"scopeDomainResponse"}},"instance_id":{"type":"string","description":"A unique identifier for the runtime instance associated with this scope.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"application_name":{"type":"string","description":"The name of the application that owns this scope.","example":"Billing Service"},"active_deployment":{"type":"object","nullable":true,"description":"The last finalized deployment for this scope, or `null` if no deployment has been completed."},"current_active_deployment":{"type":"object","nullable":true,"description":"The currently running deployment for this scope."},"in_progress_deployment":{"type":"object","nullable":true,"description":"A new deployment currently in progress, or `null` if none."},"stops_at":{"type":"string","nullable":true,"format":"date-time","description":"The ISO-8601 UTC timestamp when this scope is scheduled to stop, or `null` if not scheduled.","example":"2026-04-01T00:00:00Z"},"token_for_links":{"type":"string","description":"A JWT token for generating authenticated scope links. Only present for organizations with `generate_domain_token` enabled."},"created_at":{"type":"string","format":"date-time","description":"The ISO-8601 UTC timestamp of when the scope was created.","example":"2025-01-02T00:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The ISO-8601 UTC timestamp of when the scope was last updated.","example":"2025-06-15T12:30:00Z"},"metadata":{"type":"object","description":"The metadata loaded via the metadata catalog API.","example":{"key":"value"},"properties":{"key":{"type":"string","description":"The key of the metadata.","example":"key"},"value":{"type":"string","description":"The value of the metadata.","example":null},"additional_properties":{"type":"object","description":"Additional metadata properties, including schemas and tags.","properties":{"schemas":{"type":"array","description":"The JSON schemas of the metadata.","items":{"type":"object"}},"tags":{"type":"array","description":"Tags associated with the metadata.","items":{"type":"object","properties":{"key":{"type":"string","example":"key"},"value":{"type":"string","example":"value"}}}}}}},"title":"MetadataComponent"}},"title":"scope"}}},"title":"scopeListResponse"}}}},"4XX":{"description":"Client error responses due to invalid input or missing parameters.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific client error (e.g., 400, 401, 403, 404).","example":400},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"bad_request"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Bad Request\", \"Unauthorized\").","example":"Bad Request"},"message":{"type":"string","description":"Additional details about the error.","example":"The request was malformed or contained invalid parameters."}}}}}},"5XX":{"description":"Server error responses indicating an issue on the API side.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific server error (e.g., 500, 502, 503).","example":500},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"internal_server_error"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Internal Server Error\", \"Service Unavailable\").","example":"Internal Server Error"},"message":{"type":"string","description":"Additional details about the error.","example":"An unexpected error occurred. Please try again later."}}}}}}}}
>
  
</StatusCodes>