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

# Watch PFP Changes

> Get notified when an X account changes its profile picture

Registers an X username for profile-picture change detection. Profiles are
polled every few minutes; when the avatar changes, a `pfp_change` event is
delivered through your configured channels (webhook, Telegram, WebSocket,
SSE).

Limits: **50 watches per API key**.

<Note>
  Tracking is by **username**. If the account is no longer found (usually a
  username change), the watch is deleted automatically and you receive one final
  `pfp_change` event with `reason: "username_lost"`.
</Note>

## Request

<ParamField body="username" type="string" required>
  The X username to watch (with or without the leading `@`).
</ParamField>

## Response

<ResponseField name="data" type="object">
  The registered watch (`username`, `createdAt`).
</ResponseField>

<ResponseField name="message" type="string">
  Status message describing the result
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://scrape.st/x/pfp-watch \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "username": "elonmusk"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "username": "elonmusk",
      "createdAt": "2026-07-05T10:00:00.000Z"
    },
    "message": "PFP watch registered successfully"
  }
  ```
</ResponseExample>

## Event payload

`pfp_change` events are flat — `source` is the discriminator that tells them
apart from regular source events:

```json theme={null}
{
  "source": "pfp_change",
  "username": "elonmusk",
  "previous_pfp": "https://pbs.twimg.com/profile_images/123/old_400x400.jpg",
  "current_pfp": "https://pbs.twimg.com/profile_images/456/new_400x400.jpg",
  "reason": "pfp_changed"
}
```

`reason` is `"pfp_changed"` for an avatar change, or `"username_lost"` when
the profile 404s and the watch is removed (with `current_pfp: null` and a
human-readable `message`).