GET /diff/{pid} — State Diff Between Probe Cycles - NSP

GET /diff/{pid} shows you exactly what changed between the last two probe cycles for a tracked application. Each entry in the diff array names a state key and its value before and after the change. This is especially useful immediately after dispatching an action — call /diff to confirm which fields were affected without re-reading the entire state snapshot. If nothing changed between cycles, the diff array is empty.

Endpoint

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

integer

required

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

Response

{
  "pid": 12847,
  "app_id": "gmail-chrome-12847",
  "diff": [
    {
      "path": "inbox.unread_count",
      "before": 48,
      "after": 47
    },
    {
      "path": "inbox.emails[0].is_read",
      "before": false,
      "after": true
    }
  ],
  "captured_at": "2026-07-20T13:00:00Z",
  "previous_capture_id": "0196f4a1-3b5c-7d00-8e1f-9a0b2c3d4e5e",
  "current_capture_id": "0196f4a2-3b5c-7d00-8e1f-9a0b2c3d4e5f"
}

integer

OS process ID of the queried application.

string

Stable semantic identifier for the application.

array

Array of field-level change records. Each entry describes a single state key that changed between the two most recent probe cycles.

Show Diff entry fields

string

Dot-notation key of the state field that changed, for example "inbox.unread_count" or "inbox.emails[0].is_read".

any

The value of the field at the end of the previous probe cycle.

any

The value of the field at the end of the most recent probe cycle.

datetime

ISO 8601 timestamp of the most recent probe cycle included in the diff.

string

capture_id (UUIDv7) of the older snapshot used as the baseline.

string

capture_id (UUIDv7) of the newer snapshot used as the current state.

Example

curl -H "X-Substrate-Key: nsp_live_sk_..." \
     http://127.0.0.1:7842/substrate/v1/diff/12847

# Call immediately after an action to see what changed
result = await session.execute("archive", parameters={"email_id": "msg_18821af3"})

diff = await client.diff(12847)
for entry in diff.diff:
    print(f"{entry.path}: {entry.before!r} → {entry.after!r}")

Notes

Returns an empty diff array when no state keys changed between the last two probe cycles. This is not an error condition.
Returns 404 when the daemon has fewer than two completed probe cycles for the given PID. This happens when an application was attached very recently. Wait for at least one full probe cycle to complete and retry.

Error Responses

Status	Code	Description
`401`	`unauthorized`	Missing or invalid `X-Substrate-Key` header.
`404`	`not_found`	The specified PID is not tracked, or fewer than two probe cycles have completed for it.
`429`	`rate_limited`	Exceeded the 100 requests/second rate limit.

Endpoints

Data Models

GET /diff/{pid} — State Diff Between Probe Cycles

Endpoint

Response

Example

Notes

Error Responses

​Endpoint

​Response

​Example

​Notes

​Error Responses

Endpoint

Response

Example

Notes

Error Responses