> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get subscribers
> Returns a paginated list of users who have subscriptions to the authenticated user.
**Polling for real-time updates? Use a webhook instead.**
If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.subscription.activated`, `creator.subscription.cancel_at_period_end_changed`, `creator.subscription.deactivated` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/subscriptions).
**Required scope**
* `read:fan` — Access fan-related data and information within the platform.
## OpenAPI
````yaml /openapi.json get /subscribers
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers: []
security: []
paths:
/subscribers:
get:
summary: Get subscribers
description: >-
Returns a paginated list of users who have subscriptions to the
authenticated user.
**Polling for real-time updates? Use a webhook instead.**
If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.subscription.activated`, `creator.subscription.cancel_at_period_end_changed`, `creator.subscription.deactivated` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/subscriptions).
operationId: listSubscribers
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: number
minimum: 1
default: 1
description: Page number to retrieve (starts from 1)
required: false
description: Page number to retrieve (starts from 1)
name: page
in: query
- schema:
type: number
minimum: 1
maximum: 50
default: 15
description: 'Number of items to return per page (1-50, default: 15)'
required: false
description: 'Number of items to return per page (1-50, default: 15)'
name: size
in: query
- schema:
type: string
enum:
- name
- subscribedAt
description: Public field to sort by
required: false
description: Public field to sort by
name: sortField
in: query
- schema:
type: string
enum:
- asc
- desc
description: Sort direction
required: false
description: Sort direction
name: sortDirection
in: query
- schema:
type: string
format: date-time
description: >-
Only include users whose subscription started on or after this ISO
8601 datetime (e.g., 2024-10-20T00:00:00Z).
required: false
description: >-
Only include users whose subscription started on or after this ISO
8601 datetime (e.g., 2024-10-20T00:00:00Z).
name: startDate
in: query
- schema:
type: string
format: date-time
description: >-
Only include users whose subscription started before this ISO 8601
datetime (non-inclusive).
required: false
description: >-
Only include users whose subscription started before this ISO 8601
datetime (non-inclusive).
name: endDate
in: query
- schema:
type: string
description: >-
Opaque pagination cursor from a previous response's
pagination.nextCursor. When provided, page, sortField,
sortDirection, startDate, and endDate are ignored (the cursor
carries them); size applies when explicitly passed. Cursor
pagination is more efficient than page-based pagination for
iterating over large subscriber lists.
required: false
description: >-
Opaque pagination cursor from a previous response's
pagination.nextCursor. When provided, page, sortField,
sortDirection, startDate, and endDate are ignored (the cursor
carries them); size applies when explicitly passed. Cursor
pagination is more efficient than page-based pagination for
iterating over large subscriber lists.
name: cursor
in: query
responses:
'200':
description: List of subscribers
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
handle:
type: string
displayName:
type: string
nickname:
type:
- string
- 'null'
isTopSpender:
type: boolean
avatarUrl:
type:
- string
- 'null'
registeredAt:
type: string
format: date-time
subscription:
type:
- object
- 'null'
properties:
status:
type: string
enum:
- active
- cancelled
- pending_confirmation
- paused
description: >-
Current status of the subscriber's subscription
to this creator
price:
type: number
description: >-
Price the fan pays per subscription period, in
minor currency units (cents)
currentPeriodStart:
type: string
format: date-time
description: >-
Start of the current subscription period (ISO
8601)
currentPeriodEnd:
type:
- string
- 'null'
format: date-time
description: >-
End of the current subscription period / next
renewal date (ISO 8601), or null
autoRenewalEnabled:
type: boolean
description: >-
Whether the subscription is set to auto-renew
(rebill) at the end of the period
required:
- status
- price
- currentPeriodStart
- currentPeriodEnd
- autoRenewalEnabled
description: >-
Details of the subscriber's current subscription to
the creator, or null if none is found
firstSubscribedAt:
type:
- string
- 'null'
format: date-time
description: >-
When the fan first subscribed to the creator
(earliest across their whole subscription history),
used to tell a genuinely new fan from a
re-subscriber. Null if unknown.
required:
- uuid
- handle
- displayName
- nickname
- isTopSpender
- avatarUrl
- registeredAt
- subscription
- firstSubscribedAt
description: Array of subscribers
pagination:
type: object
properties:
page:
type: number
description: Current page number
size:
type: number
description: Number of records returned in this response
hasMore:
type: boolean
description: >-
Whether there are more items available on subsequent
pages
nextCursor:
type:
- string
- 'null'
description: >-
Opaque cursor to fetch the next page; pass it as the
cursor query parameter. Null when there are no further
results, or when sorting by name (cursor pagination is
only supported for the subscribedAt sort).
required:
- page
- size
- hasMore
- nextCursor
description: Pagination information
required:
- data
- pagination
example:
data:
- uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479
handle: sarah-jones
nickname: SarahK
displayName: Sarah Jones
isTopSpender: true
avatarUrl: https://media.fanvue.com/avatars/example-avatar.jpg
registeredAt: '2024-01-10T12:00:00.000Z'
role: creator
subscription:
status: active
price: 999
currentPeriodStart: '2026-05-15T00:00:00.000Z'
currentPeriodEnd: '2026-06-15T00:00:00.000Z'
autoRenewalEnabled: true
firstSubscribedAt: '2025-11-15T00:00:00.000Z'
- uuid: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
handle: mike-smith
nickname: null
displayName: Mike Smithly
isTopSpender: false
avatarUrl: https://media.fanvue.com/avatars/example-avatar.jpg
registeredAt: '2024-01-10T12:00:00.000Z'
role: creator
subscription:
status: cancelled
price: 1499
currentPeriodStart: '2026-06-01T00:00:00.000Z'
currentPeriodEnd: '2026-07-01T00:00:00.000Z'
autoRenewalEnabled: false
firstSubscribedAt: '2026-06-01T00:00:00.000Z'
pagination:
page: 1
size: 2
hasMore: false
nextCursor: null
'400':
description: Bad Request - API version not supported OR validation failed
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- read:fan
components:
parameters:
ApiVersionHeader:
name: X-Fanvue-API-Version
in: header
required: true
schema:
type: string
default: '2025-06-26'
example: '2025-06-26'
description: API version to use for the request
schemas:
UnsupportedVersionError:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
description: API version not supported
ValidationError:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
description: Request validation failed
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
SunsetVersionResponse:
description: API version no longer supported (sunset)
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
nextVersion:
type: string
required:
- error
- message
RateLimitResponse:
description: Too many requests - rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before retrying the request
schema:
type: integer
X-RateLimit-Limit:
description: The maximum number of requests allowed in the current window
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: The Unix timestamp (seconds) when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
BearerAuth:
type: oauth2
description: >-
OAuth 2.0 access token, presented as a JWT bearer token in the
`Authorization` header. Obtain a token via the authorization-code flow;
the scopes granted to the token determine which operations it may call.
flows:
authorizationCode:
authorizationUrl: https://auth.fanvue.com/oauth2/auth
tokenUrl: https://auth.fanvue.com/oauth2/token
refreshUrl: https://auth.fanvue.com/oauth2/token
scopes:
read:self: >-
Access your own user profile information, including basic account
details and settings.
read:chat: >-
Read chat conversations, messages, and chat-related data. This
includes viewing chat lists and message history.
write:chat: >-
Create new chats and send messages. This scope is required for any
chat-related actions that modify data.
read:experience: >-
Exchange a fan's experience token for the resolved experience and
the fan's identity, so an embedded fan-facing experience can
render the right content.
write:experience: >-
Request that the creator publish or unpublish a fan-facing
experience. The app mints a request token; the creator confirms
and Fanvue performs the change.
read:fan: Access fan-related data and information within the platform.
read:post: Read posts, including post details, comments, likes, and tips.
write:post: Create, edit, and manage posts and content on behalf of users.
read:media: Access media files, images, videos, and other content assets.
write:media: >-
Upload, modify, and manage media files and content assets. Also
required for vault folder management.
read:creator: >-
Access creator profiles, content, and creator-specific
information.
write:creator: Modify creator profiles, settings, and creator-specific data.
read:insights: >-
Access analytics, metrics, and insights data for performance
tracking.
read:tracking_links: >-
Read tracking links and the users associated with them, including
per-user tracking metadata.
write:tracking_links: Create and delete tracking links.
read:agency: Read agency information, including the agency's team members.
write:agency: >-
Manage agency team members and invites, including inviting new
team members and creators.
````