Nudges List Account

List Nudges

GET /v1/account/nudges

The pending nudges of your active account, newest first. A nudge is a finding the platform's background checks raised about the account — for example a TLS certificate about to expire, an elevated error rate, an unpaid invoice or a breached AI objective. Each one carries a short title for a card and a prompt: a first-person message that starts a conversation with the Iris AI assistant about the finding.

The same finding is never listed twice: when a check finds the same condition again it refreshes the existing nudge (new title, prompt and created_at) — and brings it back as pending if it was dismissed. Some checks also dismiss their nudge on their own once the condition is gone.

When the account has muted nudges (nudge preferences), this answers an empty list with optout: true.

Permissions: any member of the active account; no role permission is needed. The list is not paginated.

Response (200 OK)

nudges array

The pending nudges, ordered by created_at, newest first. Empty when there are none or when nudges are muted.

optout boolean

true when the account has muted nudges.

Nudge object

uuid string (uuid)

The nudge's public id. Use it in GET /v1/account/nudges/{uuid} and dismiss.

account_uuid string (uuid)

The account the nudge belongs to. Omitted when unset.

kind string

The check that raised it: cert_expiry, usage_burn, posture, unpaid_invoice, card_expiry, downgrade_grace, error_rate, suspicious_traffic, latency, domain_expiry, endpoint_down, autonomy_rollback or objective_breach.

dedupe_key string

The key that makes a finding unique within its kind (a refreshed finding keeps the same nudge). Omitted when empty.

title string

One-line summary, for a card.

prompt string

A first-person message describing the finding, written to start a conversation with Iris.

status string

pending or dismissed. This list only returns pending nudges.

severity string

Derived from kind: critical for cert_expiry and unpaid_invoice (they can take a service down or lead to suspension), warning for every other kind.

created_at datetime

When the finding was raised or last refreshed.

dismissed_at datetime

When the nudge was dismissed. Omitted while it is pending.

Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.

Errors

401 Unauthorized

Missing or invalid auth.

403 Forbidden

No active account selected, or Not a member of this account.

500 Internal Server Error

Failed to list nudges.

Request
curl "https://api.ngris.com/v1/account/nudges" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK
{
  "nudges": [
    {
      "uuid": "019b002a-8b10-7965-8ec9-97bded381ab9",
      "account_uuid": "019b83f9-a245-7b20-8e76-4bb6e86a8d59",
      "kind": "error_rate",
      "dedupe_key": "errors",
      "title": "Elevated error rate: 31% over the last hour",
      "prompt": "My account is returning a lot of errors: 31% of requests failed (HTTP 4xx/5xx, excluding firewall and rate-limit blocks) over the last hour — 412 of 1329 requests, mostly on api.acme.example.com. Diagnose the likely cause, tell me whether it's an origin/app problem on my side or something at the edge, and walk me through the fix. Don't change anything without my confirmation.",
      "status": "pending",
      "severity": "warning",
      "created_at": "2026-10-20T08:15:00Z"
    }
  ],
  "optout": false
}

Response — 200 OK (nudges muted)
{
  "nudges": [],
  "optout": true
}

PreviousAI Autonomy NextGet Nudge

On this page

List Nudges