GET /state/{pid} — Read Full Application State Snapshot - NSP

GET /state/{pid} is the primary way to read what an application currently knows about itself. The response is a flat SubstrateState document containing every labeled state object in dot-notation form, the full action schema, navigational context such as current URL and window title, and probe performance metadata. By default the daemon returns the most recent cached snapshot, which is fast. Pass fresh=true when your agent needs a guaranteed up-to-date view before making a decision.

Endpoint

GET /substrate/v1/state/{pid}
X-Substrate-Key: <key>

integer

required

OS process ID of the target application. Obtain this from GET /apps.

boolean

default:"false"

When true, the daemon triggers a new probe cycle and waits for it to complete before returning. This adds between 50 ms and 90 s of latency depending on the runtime and application complexity. Use false for polling loops where throughput matters.

Response

The response is a flat JSON object — all SubstrateState fields are at the top level rather than nested inside a wrapper.

{
  "capture_id": "0196f4a2-3b5c-7d00-8e1f-9a0b2c3d4e5f",
  "app_id": "gmail-chrome-12847",
  "app_name": "Gmail",
  "pid": 12847,
  "runtime": "v8",
  "schema_version": "1.4.2",
  "captured_at": "2026-07-20T13:00:00Z",
  "confidence": 0.97,
  "context": {
    "url": "https://mail.google.com/mail/u/0/#inbox",
    "location": "/inbox",
    "view": "gmail_inbox",
    "window_title": "Inbox (47) - Gmail",
    "window_id": "tab_8821af3"
  },
  "objects": {
    "inbox.unread_count": 47,
    "inbox.total_count": 1284,
    "inbox.emails[0].id": "msg_18821af3",
    "inbox.emails[0].thread_id": "thread_7af2b3",
    "inbox.emails[0].from": "alice@example.com",
    "inbox.emails[0].subject": "Q3 Performance Report",
    "inbox.emails[0].snippet": "Please review the attached Q3 report...",
    "inbox.emails[0].is_read": false,
    "inbox.emails[0].has_attachments": true,
    "inbox.emails[0].received_at": "2026-07-20T09:15:00Z",
    "inbox.emails[1].id": "msg_17721b3f",
    "inbox.emails[1].from": "bob@example.com",
    "inbox.emails[1].subject": "Meeting tomorrow at 3pm",
    "inbox.emails[1].is_read": false
  },
  "actions": {
    "send_reply": {
      "signature": "fn(thread_id: string, body: string, cc?: string[]) -> bool",
      "reversibility": "irreversible_write",
      "description": "Send a reply to an email thread",
      "confidence": 0.99,
      "parameters": [
        { "name": "thread_id", "type_name": "string", "required": true },
        { "name": "body", "type_name": "string", "required": true },
        { "name": "cc", "type_name": "array", "required": false }
      ]
    },
    "archive": {
      "signature": "fn(email_id: string) -> bool",
      "reversibility": "reversible_write",
      "confidence": 0.99,
      "parameters": [
        { "name": "email_id", "type_name": "string", "required": true }
      ]
    }
  },
  "probe_metadata": {
    "capture_latency_ms": 28,
    "labeling_latency_ms": 12,
    "total_latency_ms": 51,
    "raw_object_count": 8472,
    "filtered_object_count": 23,
    "cache_hit": true,
    "dom_tier_used": false,
    "probe_tier": "aso_fast"
  }
}

Top-Level Fields

string (UUIDv7)

Time-ordered unique identifier for this specific capture. Use it to correlate snapshots with diff and watch events.

string

Stable semantic identifier for the application. Survives daemon restarts.

string

Human-readable application name.

integer

OS process ID.

string

Runtime kind: v8, jvm, clr, native, or unknown.

string

Semantic version of the state schema (semver). Use this value when submitting corrections via POST /learn/{pid}.

datetime

ISO 8601 timestamp of when this snapshot was captured.

float

Overall state quality score from 0.0 to 1.0.

AppContext

Navigational context for the application — URL, view name, window title, and window ID.

object

Flat dot-notation map of every labeled state key and its current value. Array elements use bracket notation, for example inbox.emails[0].subject.

object

Map of action names to their typed schemas. Each entry includes the function signature, reversibility classification, parameter list, and confidence score.

object

Probe performance metadata. Useful for debugging latency and understanding which capture path was used.

Show probe_metadata fields

integer

Time to read raw data from the runtime, in milliseconds.

integer

Time for the semantic labeling pass, in milliseconds.

integer

End-to-end wall time for the probe cycle, in milliseconds.

integer

Number of objects extracted before noise filtering.

integer

Number of objects retained after filtering. This matches object_count in GET /apps.

boolean

true when the schema was served from the daemon’s schema cache rather than re-inferred from the runtime.

string

The capture path used. One of: aso_fast, heap_snapshot, jvmti, clr_mmf.

Examples

# Cached snapshot (fast)
curl -H "X-Substrate-Key: nsp_live_sk_..." \
     http://127.0.0.1:7842/substrate/v1/state/12847

# Fresh probe cycle (slower but guaranteed current)
curl -H "X-Substrate-Key: nsp_live_sk_..." \
     "http://127.0.0.1:7842/substrate/v1/state/12847?fresh=true"

# Cached (fast)
state = await client.get_state(12847)
print(state.confidence)
print(state.objects.get("inbox.unread_count"))

# Fresh (slower)
state = await client.get_state(12847, fresh=True)

# Via session
session = await client.attach("Gmail")
state = await session.refresh()

Error Responses

Status	Code	Description
`404`	`not_found`	The PID is not tracked. Confirm the process is running and visible to the daemon.
`503`	`probe_not_ready`	The cold probe for this process is still in progress. Retry after a short delay.
`504`	`probe_timeout`	A `fresh=true` probe cycle did not complete within the timeout. The application may be unresponsive.

Endpoints

Data Models

GET /state/{pid} — Read Full Application State Snapshot

Endpoint

Response

Top-Level Fields

Examples

Error Responses

​Endpoint

​Response

​Top-Level Fields

​Examples

​Error Responses

Endpoint

Response

Top-Level Fields

Examples

Error Responses