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

# Fanvue API Overview (/api-reference/fanvue)

import { BotMessageSquareIcon, RocketIcon, SmilePlusIcon } from "lucide-react";

## What to expect

Our Fanvue API gives you the same API key, credits and `_meta` you know from our OnlyFans and Fansly APIs, covering chats, messages, fans, subscribers and earnings insights.

<Callout title="Rolling out team by team">
  We're enabling Fanvue for teams gradually. Until it's on for yours, the **Fanvue** tab doesn't appear on **Accounts**, every `/api/fanvue` endpoint answers `404` and the [Fanvue webhook events](/webhooks/fanvue-events) aren't offered. [Email us](mailto:hello@onlyfansapi.com) if you'd like access.
</Callout>

## Connecting a Fanvue account

Fanvue creators connect by signing in with their Fanvue login, so connecting only happens in the browser. Open the **Fanvue** tab on **Accounts** in the [OnlyFans API Console](https://app.onlyfansapi.com), connect the creator, then use [List Accounts](/api-reference/fanvue/account/list-accounts) to get the account ID the other endpoints take. [Get Public Profile](/api-reference/fanvue/profiles/get-public-profile) is the one endpoint that needs no connected account.

## Responses are Fanvue's, passed through

Every endpoint under `/api/fanvue/{fanvueAccount}` proxies one Fanvue endpoint and returns its JSON body untouched, under a `data` key:

```json
{
    "data": { "...": "exactly what Fanvue returned" },
    "_meta": { "_credits": "...", "_cache": "...", "_rate_limits": "..." }
}
```

`_meta` is ours and carries the credit charge, cache state and your OnlyFansAPI rate limits. Nothing inside `data` is renamed or reshaped to match our OnlyFans and Fansly APIs, so [Fanvue's own API reference](https://api.fanvue.com/docs) is the field-level source of truth. Each endpoint page names the Fanvue endpoint it proxies.

The **Account** endpoints, **Get Public Profile** and **List Expiring Subscribers** are the exceptions. **Account** reads our own record of a connected creator and answers without `data` or `_meta`. **Get Public Profile** keeps the envelope, but reads fanvue.com's website rather than Fanvue's API, so its shape is unofficial and can change without notice. [List Expiring Subscribers](/api-reference/fanvue/fans/list-expiring-subscribers) walks several of Fanvue's subscriber pages in one call and builds its own `data`. It keeps only the subscribers due to lapse, sorts them by `subscription.currentPeriodEnd` and returns them with a `nextCursor` but no `total`.

## Errors

A proxied call keeps Fanvue's status code. A 4xx carries Fanvue's own answer alongside ours:

```json
{
    "error": "FANVUE_COM_ERROR",
    "message": "Missing scope read:insights",
    "description": "This error happened while our servers tried to communicate with Fanvue in real time.",
    "fanvue_response": {
        "status": 403,
        "body": { "error": "insufficient_scope", "message": "Missing scope read:insights" }
    }
}
```

A Fanvue 5xx or timeout becomes a `502` with no `fanvue_response`.

## Pagination

Fanvue's list endpoints use cursor pagination, passed through as-is. A page carries `nextCursor`, plus `total` on the lists Fanvue computes one for:

```json
{
    "data": { "data": ["..."], "nextCursor": "eyJ2IjoyfQ", "total": 41 }
}
```

Send that value back as `cursor` for the next page, and stop when `nextCursor` is `null`. Keep `size` the same for the whole walk.

[List Chat Messages](/api-reference/fanvue/chat-messages/list-chat-messages) pages by date instead. It returns a `dateFilter` that you send back as `sentBefore` and `receivedBefore`. A `null` `dateFilter` means there is nothing older.

## Rate limits

Fanvue rate limits each connected account to 200 requests per 60 seconds, and [Check Online Status](/api-reference/fanvue/fans/check-online-status) to 80 per 60 seconds. When Fanvue answers `429` we don't retry. We answer `429` and copy Fanvue's `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers onto our response, so you can back off on the real budget.

## Credits

Each request that Fanvue answers costs one credit, including a 4xx such as a missing scope. A `429`, a `502` or a timeout costs nothing. [List Expiring Subscribers](/api-reference/fanvue/fans/list-expiring-subscribers) walks several Fanvue pages in one call and costs one credit per page. Successful responses report the charge and your remaining balance under `_meta._credits`. Error responses carry no `_meta`, so a charged 4xx doesn't report it.

[Get Public Profile](/api-reference/fanvue/profiles/get-public-profile) is cached for 15 minutes. A lookup served from the cache is free, and the profile can be up to 15 minutes old. Add `?fresh=true` to skip the cache, which costs a credit. An unknown handle answers `404` and costs nothing.

## Reconnecting an account

Fanvue access tokens last about an hour. We refresh them for you before they expire, and again if Fanvue answers `401` anyway, so this is normally invisible. When Fanvue permanently rejects the refresh, the account moves to `needs_reauth` and every endpoint that calls Fanvue for it answers `401`:

```json
{
    "error": "SESSION_EXPIRED:NEEDS_REAUTHENTICATION",
    "message": "This Fanvue account needs re-authentication. Please reconnect it from the Dashboard.",
    "description": "Fanvue rejected this account's credentials. Reconnect the account before making further requests."
}
```

Retrying won't clear it. Open the **Fanvue** tab on **Accounts** in the [OnlyFans API Console](https://app.onlyfansapi.com) and use **Reconnect** on that account. Once it reads Active again, your existing account ID keeps working.

The **Account** endpoints don't call Fanvue, so they keep answering while an account needs reconnecting. [List Accounts](/api-reference/fanvue/account/list-accounts) and [Get Account](/api-reference/fanvue/account/get-account) report its `status` as `needs_reauth`, which is how to spot one from your code.

<h2 className="text-fd-primary">
  Haven't found what you're looking for?
</h2>

<Cards className="grid grid-cols-3 gap-4 @container">
  <Card icon={<RocketIcon />} title="Explore our full API reference in the sidebar" href="/api-reference/fanvue">
    Check out the sidebar to explore all available Fanvue endpoints.
  </Card>

  <Card icon={<BotMessageSquareIcon />} title="Ask our AI chatbot">
    Our AI chatbot can help you find the right endpoint for your use case. Click the "Ask AI" button in the bottom right to get started.
  </Card>

  <Card icon={<SmilePlusIcon />} title="Request a new functionality" href="mailto:hello@onlyfansapi.com">
    Need something specific? Let us know! We're constantly adding new endpoints based on user feedback.
  </Card>
</Cards>