> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Notifications

> List notifications for the authenticated agent

## Overview

Returns a list of notifications for the agent. Notifications are created when jobs complete, resources expire, or other important events occur.

## Authentication

Requires `X-Agent-ID` header with the agent's wallet address.

Reads return private, per-agent data, so they are protected by a signed **read proof** (`x-agent-proof` header) proving you control that wallet. The OneShot SDK signs and sends this automatically (TypeScript ≥ 0.25.0, Python ≥ 0.17.0). This is rolling out in log-only mode — requests without the proof still succeed today and will be rejected once enforcement is enabled; raw HTTP callers should start sending it. See [Read Proof Authentication](/sdk/overview#read-authentication).

## Query Parameters

<ParamField query="unread" type="boolean" default="false">
  If `true`, only return unread notifications
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of notifications to return (max: 100)
</ParamField>

## Response

<ResponseField name="notifications" type="array">
  Array of notification objects

  <Expandable title="Notification object">
    <ResponseField name="id" type="string">
      Unique notification ID (UUID)
    </ResponseField>

    <ResponseField name="agentId" type="string">
      Agent ID this notification belongs to
    </ResponseField>

    <ResponseField name="type" type="string">
      Notification type: `job_completed`, `job_failed`, `voice_completed`, `sms_completed`, `credit_issued`, `domain_expiring`, `phone_expiring`
    </ResponseField>

    <ResponseField name="title" type="string">
      Short notification title
    </ResponseField>

    <ResponseField name="body" type="string">
      Optional detailed message
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Additional context (jobId, tool, amounts, etc.)
    </ResponseField>

    <ResponseField name="read" type="boolean">
      Whether the notification has been read
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp when notification was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number">
  Number of notifications returned
</ResponseField>

## Example Request

```bash theme={null}
curl -X GET "https://win.oneshotagent.com/v1/tools/notifications?unread=true&limit=10" \
  -H "X-Agent-ID: 0xYourWalletAddress"
```

## Example Response

```json theme={null}
{
  "notifications": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agentId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "voice_completed",
      "title": "Voice call completed - Objective achieved",
      "body": "Successfully made dinner reservation for 2 at 7pm",
      "metadata": {
        "jobId": "job_abc123",
        "targetNumber": "+14155551234",
        "durationSeconds": 120,
        "successEvaluation": "pass"
      },
      "read": false,
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "agentId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "domain_expiring",
      "title": "domain myagent.com expiring",
      "body": "Will be released on 2024-02-01 due to inactivity",
      "metadata": {
        "resourceType": "domain",
        "resourceName": "myagent.com",
        "removalDate": "2024-02-01T00:00:00Z"
      },
      "read": false,
      "createdAt": "2024-01-10T08:00:00Z"
    }
  ],
  "count": 2
}
```

## SDK Usage

```typescript theme={null}
import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

// Get all notifications
const all = await agent.notifications();
console.log(`You have ${all.count} notifications`);

// Get only unread
const unread = await agent.notifications({ unread: true, limit: 10 });
for (const n of unread.notifications) {
  console.log(`[${n.type}] ${n.title}`);
}
```

## Notification Types

| Type              | Description                                        |
| ----------------- | -------------------------------------------------- |
| `job_completed`   | A job finished successfully                        |
| `job_failed`      | A job failed with an error                         |
| `voice_completed` | Voice call completed (includes success evaluation) |
| `sms_completed`   | SMS batch delivery completed                       |
| `credit_issued`   | Credit was issued to your account                  |
| `domain_expiring` | Domain will be released due to inactivity          |
| `phone_expiring`  | Phone number will be released due to inactivity    |