Sign in
Scope

Read a scope

Read a specific scope.

get/scope/{id}

Path parameters

idinteger required

The ID of the scope.

Query parameters

metadata_includestring

Comma-separated properties that should be included in the metadata response. Available values: [schemas, tags].

include_messagesboolean

Specifies whether it includes messages in the response.

Response

An object representing the scope.

idinteger required

A system-wide unique ID for the scope.

namestring required

The name of the scope.

asset_namestring

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.

slugstring required

An application-wide unique slug for the scope.

domainstring required

An application-wide unique domain for the scope.

application_idinteger required

The ID of the application that owns this scope.

capabilitiesobject

Defines optional features such as logging, auto scaling, and spot instances. See the capabilities documentation for details.

messagesobject

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_createdboolean

Indicates whether the scope was provisioned externally. false when provisioned by nullplatform, true if created externally (e.g., via Terraform).

tagsstring[]

Tags associated with the scope.

profilesstring[]

NRN profiles that must be applied to this scope, independent of runtime configurations.

dimensionsobject

Defines runtime configuration dimensions, such as environment or region, that apply to this scope.

runtime_configurationsinteger[]

Runtime configurations that apply to this scope based on its dimensions.

instance_idstring

A unique identifier for the runtime instance associated with this scope.

application_namestring

The name of the application that owns this scope.

active_deploymentobject nullable

The last finalized deployment for this scope, or null if no deployment has been completed.

current_active_deploymentobject nullable

The currently running deployment for this scope.

in_progress_deploymentobject nullable

A new deployment currently in progress, or null if none.

stops_atstring date-time nullable

The ISO-8601 UTC timestamp when this scope is scheduled to stop, or null if not scheduled.

token_for_linksstring

A JWT token for generating authenticated scope links. Only present for organizations with generate_domain_token enabled.

created_atstring date-time

The ISO-8601 UTC timestamp of when the scope was created.

updated_atstring date-time

The ISO-8601 UTC timestamp of when the scope was last updated.

Example response

{
  "id": 1234,
  "name": "Billing API",
  "asset_name": "main-asset",
  "type": "custom",
  "provider": "9e84a5c3-6c2e-4f15-90b0-1c67fd37f6e8",
  "status": "active",
  "slug": "billing-api",
  "domain": "billing-api-prod.nullapps.io",
  "application_id": 2345,
  "requested_spec": {
    "memory_in_gb": 2,
    "cpu_profile": "standard",
    "local_storage_in_gb": 8
  },
  "tier": "important",
  "tags": [
    "requires_deployment",
    "high_priority"
  ],
  "profiles": [
    "environment_production"
  ],
  "dimensions": {
    "environment": "production"
  },
  "runtime_configurations": [
    1234,
    2345
  ],
  "domains": [
    {
      "id": "e78a0d21-3c48-7421-81cd-203fe84b8e47",
      "name": "api.crypto-inc.com",
      "type": "scope",
      "selector": {
        "organization_id": "1",
        "nrn": "organization=1:account=2:namespace=3:application=4",
        "scope_id": "1234"
      },
      "status": "active",
      "created_at": "2025-01-02T00:00:00Z",
      "updated_at": "2025-02-02T00:00:00Z"
    }
  ],
  "instance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "application_name": "Billing Service",
  "stops_at": "2026-04-01T00:00:00Z",
  "created_at": "2025-01-02T00:00:00Z",
  "updated_at": "2025-06-15T12:30:00Z",
  "metadata": {
    "key": "value"
  }
}

Changes