---
title: "Create or update a monitor by username"
method: PUT
path: "/api/v1/monitors/username/{username}"
tags: ["Monitors"]
---

# Create or update a monitor by username

`PUT /api/v1/monitors/username/{username}`

## Request

- Base URL: `https://xquik.com`
- URL: `https://xquik.com/api/v1/monitors/username/{username}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Creates the monitor if it does not exist, or updates it if it does. Send the same call twice & you still have 1 monitor. A new monitor answers 201 & an update answers 200. Both carry `created`, so you know which one ran. Creating needs the credits of the first hour, then costs 30 credits an hour. A stopped monitor turns back on & counts as created. Updating is free & replaces the event types. It changes the name only when you send one.

## Path parameters

- `username` string, required

## Request body

- object
  - `eventTypes` EventType[], required: Array of event types to subscribe to.
  - `name` string, nullable: Your label for the monitor. Its events carry it as monitorName. Leave it out to keep the current label, or send null to remove it.

## Response `200`

Running monitor updated

- object: Account monitor that tracks activity for a given X user.
  - `id` string, required
  - `username` string, required
  - `xUserId` string, required
  - `name` string: Customer-set label of the account monitor, when set.
  - `eventTypes` EventType[], required: Array of event types to subscribe to.
  - `isActive` boolean, required
  - `createdAt` string, date-time, required
  - `nextBillingAt` string, date-time, required: Next hourly credit charge time for this account monitor.
  - `pausedReason` 'insufficient_credits' | 'x_account_protected' | 'x_user_not_found': Why Xquik paused this account monitor. `insufficient_credits` means the balance could not pay an hour, so add credits & resume. The other 2 mean X stopped showing the account. Absent when the monitor is active or you paused it yourself.
  - `pausedAt` string, date-time: When Xquik paused this account monitor.
  - `created` boolean, required: False, since this call updated a running monitor.

## Other responses

- `201`: Monitor created or turned back on
- `400`: Invalid input. A value past its maxLength gets this answer, & the message names the field & its limit. Bad input costs nothing, since it's refused before any read.
- `401`: Unauthenticated
- `402`: Payment required. MPP reads include `WWW-Authenticate`. Authenticated reads include balances, plus checkout when the key can open it. A key that reads only gets the account page instead. A failed request never creates checkout. A caller on a plan gets top-up only, plus `credits_renew_at` when the plan renews. Guest keys offer top-up.
- `403`: The API key lacks the monitors scope this route needs. A paused API key gets `api_key_paused`, so resume it on the dashboard.
- `404`: X shows no profile for the account. `reason` says why. It is `not_found` for a handle or ID no account holds, which X answers for a deactivated account too. It is `suspended` when X suspended the account, with the message "X suspended this account. Choose another account."
- `429`: Too many requests right now. Each user gets 500 reads a second, 6,000 changes to Xquik resources a minute & 120 X actions a minute. X actions post, like, follow, message or edit through a connected X account. `x_api_rate_limited` means X limits this read for now. Neither answer costs anything. Wait for the seconds in `Retry-After`, then retry.
- `500`: Unexpected error.
- `default`: Unexpected error.

## Changes

- **2026-11-18** `fe9dc4f8a127`: 1 info
  - endpoint added
- **2026-11-18** `2284c0998114`: 1 breaking
  - api path removed without deprecation
- **2026-11-18** `a291f0b82030`: 1 info
  - endpoint added
- **2026-11-17** `e1e106c83615`: 1 breaking
  - api path removed without deprecation
- **2026-11-17** `d40150ef20b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/xquik-dev/apis/xquik-api/changes/api/v1/monitors/username/:username/put.md)

---

[API](https://skmtc.dev/xquik-dev/apis/xquik-api.md) - [All operations](https://skmtc.dev/xquik-dev/apis/xquik-api/llms.txt) - [OpenAPI document](https://skmtc.dev/xquik-dev/apis/xquik-api/revisions/fe9dc4f8a127?raw)
