Response Structure

Understanding API response format, metadata, and headers

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": 1000,
      "remaining_minute": 59,
      "remaining_day": 988
    }
  }
}

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: Requests allowed per day
   • remaining_minute: Remaining requests this minute
   • remaining_day: Remaining requests today

Response Headers

Each response includes comprehensive metadata in the headers:

Available Headers

content-type:                   application/json
x-ofapi-credits-balance:        9852
x-ofapi-credits-used:           0
x-ofapi-is-cached:              true
x-rate-limit-limit-day:         1000
x-rate-limit-limit-minute:      60
x-rate-limit-remaining-day:     988
x-rate-limit-remaining-minute:  59

Header Categories

1. Content Headers

   • content-type: Always application/json

2. Credit Headers

   • x-ofapi-credits-used: Credits used by this request
   • x-ofapi-credits-balance: Your remaining credit balance
   • x-ofapi-is-cached: Whether response was cached

3. Rate Limit Headers

   • x-rate-limit-limit-minute: Per-minute limit
   • x-rate-limit-limit-day: Daily limit
   • x-rate-limit-remaining-minute: Remaining minute requests
   • x-rate-limit-remaining-day: Remaining daily requests

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

The same information is available in both headers and the _meta object. Use headers for quick access in code, and the _meta object for more detailed information including notes and timestamps.