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

# User engagement rate insights, X (Twitter) API docs

> Get a Twitter or X profile's engagement rate, average likes, replies, reposts and views per post, posting rate, and top post from its recent posts. 1 credit.

> For the complete documentation index, see [llms.txt](https://docs.xquik.com/llms.txt).

`GET https://xquik.com/api/v1/x/users/{id}/insights`

**1 credit per report**, whatever it reads · A user X doesn't know is free

[All plans](https://xquik.com) from \$0.00012/credit · Supports [guest paid reads](https://docs.xquik.com/guides/guest-wallets.md)

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
curl "https://xquik.com/api/v1/x/users/nasa/insights" \
  -H "x-api-key: xq_your_api_key_here" | jq
```

```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
const response = await fetch("https://xquik.com/api/v1/x/users/nasa/insights", {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const body = await response.json();
if (!response.ok) throw new Error(JSON.stringify(body));

const { insights } = body;
console.log(
  `@${insights.userName}: ${insights.engagementRate}% engagement, ${insights.postsPerDay} posts a day`,
);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
import requests

response = requests.get(
    "https://xquik.com/api/v1/x/users/nasa/insights",
    headers={"x-api-key": "xq_your_api_key_here"},
)
body = response.json()
if not response.ok:
    raise RuntimeError(body)

insights = body["insights"]
print(f'@{insights["userName"]}: {insights["engagementRate"]}% engagement, {insights["postsPerDay"]} posts a day')
```

## A profile's engagement at a glance

Use `GET /x/users/{id}/insights` to size up an account before you work with it. Name the user by user ID, username, or
profile URL.




The report reads the profile's counts and its 20 most recent posts. Set `limit` to read more. It still costs 1 credit.
A read stops at your count or the account's oldest post. It also stops after about 40 seconds. A read of more than
800 posts can miss a few. `sample.read` says how many posts it read.
`sample.posts` says how many of them the averages used. Reposts and the pinned post stay out. So the averages describe
the account's own recent posts. Engagements are likes, replies, reposts, and quotes.




A rate is `null` when nothing divides it. One case is a profile without posts of its own.




A protected account's posts are private. Its report has counts and account age, `postsPrivate: true`, and a
`message` that says so. It costs the same 1 credit.

## Path parameters

| Path parameter | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | User ID, username with or without `@`, or URL-encoded profile URL, such as `x.com/nasa`. See [path IDs](https://docs.xquik.com/api-reference/overview.md#path-ids). |

## Query parameters

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `limit` | `integer` | No | Recent posts to read, from `1` up. `pageSize`, `count`, `max_results`, `maxItems`, `max_items` & `per_page` are accepted aliases. Default `20`. |

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `fields` | `string` | No | Fields to keep in each row, comma-separated, such as `id,text,author.username`. Use dots for nested fields. Case & underscores do not matter. A row that lacks a field leaves it out. Cursors, counts & diagnostics always stay. An unknown name returns `400 unknown_field` with the valid names, before any read. The price stays the same. |
| `omit` | `string` | No | Fields to drop from each row, comma-separated, such as `entities,media`. It takes the same names as `fields`. With `fields`, it drops from the kept fields. |

## Headers

| Header | Type | Required | Description |
| - | - | - | - |
| `x-api-key` | `string` | No | Full account key. Sessions and OAuth also work. |
| `Authorization` | `string` | No | `Bearer xq_your_guest_key_here` for `paid_reads`. |

## Response

### 200 OK

| Field | Type | Description |
| - | - | - |
| `insights` | `object` | |
| `insights.userId` | `string` | ID of the profile. |
| `insights.userName` | `string` | Username of the profile. |
| `insights.followers` | `number` | Followers. |
| `insights.following` | `number` | Accounts the user follows. |
| `insights.posts` | `number` | Posts the user has made. |
| `insights.accountAgeDays` | `number \| null` | Whole days since the account joined X. |
| `insights.postsPrivate` | `boolean` | `true` when only the account's followers see its posts. The report then has its counts only. |
| `insights.sample` | `object` | The recent posts the read covered. `read` counts them all. `posts` counts those the averages used. `oldestAt` and `newestAt` say when the oldest and newest of those went up. |
| `insights.averages` | `object \| null` | Likes, replies, reposts, quotes, bookmarks, views, and engagements per post. `null` without posts. |
| `insights.engagementRate` | `number \| null` | Average engagements per post, as a percent of followers. |
| `insights.engagementPerView` | `number \| null` | Engagements as a percent of views across the sample. |
| `insights.postsPerDay` | `number \| null` | Sampled posts per day, from the oldest one until now. |
| `insights.topPostId` | `string \| null` | The sampled post with the most engagements. |
| `message` | `string` | Says why the report has counts only, for a protected account. |

### 400 Invalid input

`{ "error": "invalid_user_id" }`




Send a user ID, a username, or a profile URL.

### 404 User not found

A user X doesn't know is free.

### 401 Unauthenticated

Anonymous requests get `WWW-Authenticate: Bearer` and a guest wallet checkout action. This is not a Payment challenge.

### 402 Payment required

Account keys get account options. Guest keys get guest top-up only.
No checkout starts automatically. Confirm any payment action.

### 502 X API unavailable

The read service returned an error. Retry after a short delay.

> [!NOTE]
>
> **Related.** [Tweet engagement insights](https://docs.xquik.com/api-reference/x/tweet-engagement-insights.md) · [Get user](https://docs.xquik.com/api-reference/x/twitter-profile-lookup.md) · [User timeline](https://docs.xquik.com/api-reference/x/user-tweets.md)

> [accordion] Related follower, list & community APIs
>
> * Profiles
>   * [Search users](https://docs.xquik.com/api-reference/x/search-users.md)
>   * [Search autocomplete](https://docs.xquik.com/api-reference/x/search-autocomplete.md)
>   * [Get user](https://docs.xquik.com/api-reference/x/twitter-profile-lookup.md)
>   * [Batch users](https://docs.xquik.com/api-reference/x/batch-users.md)
> * Followers
>   * [Followers](https://docs.xquik.com/api-reference/x/followers.md)
>   * [Following](https://docs.xquik.com/api-reference/x/following.md)
>   * [Follower IDs](https://docs.xquik.com/api-reference/x/follower-ids.md)
>   * [Following IDs](https://docs.xquik.com/api-reference/x/following-ids.md)
>   * [Creator subscriptions](https://docs.xquik.com/api-reference/x/user-subscriptions.md)
>   * [Affiliates](https://docs.xquik.com/api-reference/x/user-affiliates.md)
>   * [Similar accounts](https://docs.xquik.com/api-reference/x/user-similar.md)
>   * [Translate bio](https://docs.xquik.com/api-reference/x/user-bio-translation.md)
>   * [User insights](https://docs.xquik.com/api-reference/x/user-engagement-insights.md)
>   * [Verified followers](https://docs.xquik.com/api-reference/x/verified-followers.md)
>   * [Followers you know](https://docs.xquik.com/api-reference/x/followers-you-know.md)
>   * [Check follower](https://docs.xquik.com/api-reference/x/check-follower.md)
> * Lists
>   * [Search lists](https://docs.xquik.com/api-reference/x/search-lists.md)
>   * [User lists](https://docs.xquik.com/api-reference/x/user-lists.md)
>   * [List memberships](https://docs.xquik.com/api-reference/x/user-list-memberships.md)
>   * [List details](https://docs.xquik.com/api-reference/x/list-details.md)
>   * [List members](https://docs.xquik.com/api-reference/x/list-members.md)
>   * [List followers](https://docs.xquik.com/api-reference/x/list-followers.md)
> * Communities
>   * [Find](https://docs.xquik.com/api-reference/x/community-find.md)
>   * [Popular](https://docs.xquik.com/api-reference/x/community-popular.md)
>   * [Topics](https://docs.xquik.com/api-reference/x/community-topics.md)
>   * [Suggested](https://docs.xquik.com/api-reference/x/community-suggested.md)
>   * [Details](https://docs.xquik.com/api-reference/x/community-info.md)
>   * [Members](https://docs.xquik.com/api-reference/x/community-members.md)
>   * [Member search](https://docs.xquik.com/api-reference/x/community-member-search.md)
>   * [Moderators](https://docs.xquik.com/api-reference/x/community-moderators.md)
>   * [Timeline](https://docs.xquik.com/api-reference/x/community-tweets.md)
>   * [Media](https://docs.xquik.com/api-reference/x/community-media.md)
>   * [Keyword search](https://docs.xquik.com/api-reference/x/community-search.md)
>   * [Tweets search](https://docs.xquik.com/api-reference/x/community-tweets-search.md)

## Response examples

### 200 example

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
{
  "insights": {
    "userId": "11348282",
    "userName": "NASA",
    "followers": 92376187,
    "following": 115,
    "posts": 74336
  }
}
```

* **400** `{ "error": "invalid_input", "message": "Invalid input. Check the request body." }`
* **401** `{ "error": "unauthenticated", "message": "Authentication required." }`
* **402** `{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }`
* **403** `{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }`
* **404** `{ "error": "user_not_found", "message": "X user not found. Check the username." }`
* **424** `{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }`
* **429** `{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }`
* **502** `{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }`
* **503** `{ "error": "x_api_unavailable", "message": "Xquik is busy right now. Retry shortly." }`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.