--- id: scope-read title: "Read a scope" description: "Read a specific scope." sidebar_label: "Read a scope" 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"; Read a specific scope. ℹ️ **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"}}}},"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."}}}}}}}} >