> ## 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 Profile Changes

> Get notified when an X account changes its handle or profile picture

Registers an X account for profile change detection. The watch is anchored to
the account's **stable user id**, so it survives username changes. When the
avatar or the handle changes, a `profile_change` event is delivered through your
configured channels (webhook, Telegram, WebSocket).

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

<Note>
  Because the watch follows the stable user id, a username change no longer ends
  tracking — you get a `profile_change` event with `reason: "username_changed"`
  and the watch keeps running under the new handle.
</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`, `userId`, `createdAt`).
</ResponseField>

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

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

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

## Event payload

`profile_change` events are flat — `source` is the discriminator that tells them
apart from regular source events. The fields present depend on `reason`:

```json theme={null}
{
  "source": "profile_change",
  "username": "elonmusk",
  "reason": "pfp_changed",
  "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` is one of:

* `"pfp_changed"` — the avatar changed. Carries `previous_pfp` / `current_pfp`.
* `"username_changed"` — the handle changed. Carries `previous_username` /
  `current_username`; `username` is the new handle.