Response Structure

Response Format

Every API response follows a consistent structure with two main components:

1. The data field containing OnlyFans information
2. Optional _pagination field with pagination information, if the endpoint is paginated
3. The _meta object containing request metadata

Here's an example response:

Response Body Structure

{
  "data": {
    // OnlyFans response data
    "view": "f",
    "avatar": "https://...",
    "isFriend": false,
    "isBlocked": false,
    "canReport": false
  },
  "_meta": {
    "_credits": {
      "used": 0,
      "balance": 9852,
      "note": "Cache HIT. No credits debited"
    },
    "_cache": {
      "is_cached": true,
      "cached_at": "2025-01-29T16:30:43+00:00",
      "note": "Add ?fresh=true to the request URL to skip the cache and get a fresh response from OnlyFans"
    },
    "_rate_limits": {
      "limit_minute": 60,
      "limit_day": null, // Legacy
      "remaining_minute": 59,
      "remaining_day": null, // Legacy
      "notice": "We have decided to remove our daily rate limits. Please remove any references to this in your integrations."
    }
  }
}

The data Field

The data field always contains the actual OnlyFans response data. Its structure varies depending on the endpoint being called. For example:

• Profile information for /profiles/{username}
• Message data for /messages endpoints
• Subscriber data for /subscribers endpoints

The optional _pagination field

Some endpoints return paginated data. For example, /chats, /chats/XYZ/messages or /tracking-links.

In this case, the response will include a _pagination field with the next_page field that you can use to fetch the next page of results.

If there are no more pages, the next_page field will be null.

{
  "data": {
    // OnlyFans response data
  },
  "_meta": {
    "_pagination": {
      "next_page": "https://app.onlyfansapi.com/api/acct_XXXXXXXXXXX/chats/?offset=10&limit=10"
    }
  }
}

The _meta Object

The _meta object contains three sections of metadata about your request:

1. _credits: Credit usage information

   • used: Credits consumed by this request
   • balance: Your remaining credit balance
   • note: Additional information about credit usage

2. _cache: Caching status and information

   • is_cached: Whether this response was served from cache
   • cached_at: When the response was cached
   • note: Instructions for bypassing cache if needed

3. _rate_limits: Rate limiting information

   • limit_minute: Requests allowed per minute
   • limit_day: Legacy: Requests allowed per day (removed)
   • remaining_minute: Remaining requests this minute
   • remaining_day: Legacy: Remaining requests today (removed)

Error Responses

When a request fails, the response drops the data field and returns a top-level error string alongside the matching HTTP status code:

{
  "error": "Not Found"
}

Some errors carry an additional machine-readable code field. Treat code as optional: error is always present, code is only added where we can be more specific than the status code alone.

account_not_found

Returned with a 404 when the acct_ ID in the request URL (or in the Account-Id header) does not resolve to a connected account on your team:

{
  "error": "Not Found",
  "code": "account_not_found"
}

The account is gone — it was disconnected, deleted, or never existed — so the fix is to reconnect the creator rather than to correct a resource ID. For privacy reasons, an acct_ ID that belongs to a different team returns this exact same response.

To find out the moment an account is disconnected instead of on your next request, subscribe to the accounts.disconnected webhook.

A 404 without a code means the endpoint or the requested resource doesn't exist; the account itself resolved fine.

Response Headers

Each response includes comprehensive metadata in the headers:

Cache Control

You can control caching behavior using query parameters:

• By default, responses are cached when possible (only for public endpoints)
• Add ?fresh=true to force a fresh response from OnlyFans
• Cached responses don't consume credits
• Cache duration varies by endpoint