---
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","maximum":200,"description":"The maximum number of results to return per page. The maximum allowed value is 200.","example":200}}},"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>