ONonlyfansapi
Fans

List Expired Fans

Changed on

Get a paginated list of expired fans for an Account. Newest fans are first. Paginate by following _pagination.next_page until it is null (data.hasMore is the authoritative flag). Do NOT use the page's item count to detect the last page — OnlyFans occasionally returns fewer than limit items (e.g. 19 for limit=20) on a non-final page because it filters entries server-side; no fans are skipped.

Supports filter[max_total_spent] (e.g. filter[max_total_spent]=0 for fans who have never spent), which OnlyFans itself cannot do. Those requests are answered from OnlyFansAPI's own fan index rather than proxied, so the page is limited to fans we have already indexed for this account — see data._source in the response.

get/api/{account}/fans/expired

Request

  • Base URL
    https://app.onlyfansapi.com
  • URL
    https://app.onlyfansapi.com/api/{account}/fans/expired
  • Auth
    HTTP bearer

Query parameters

limitinteger

Number of fans to return (1-20). OnlyFans does not allow more than 20 per page. Must be at least 1. Must not be greater than 20.

Example:20
offsetinteger

Number of fans to skip. Must be at least 0.

type'active' | 'expired' | 'all'

Filter by fan type.

filterobject

Filter by specific fields.

filter.online1 | 0 nullable

Filter by online status (1 for online fans). Must use bracket syntax: filter[online]=1 — the dot form (filter.online=1) is rejected with a 422, because PHP rewrites it to filter_online and the filter could not be applied.

filter.total_spentinteger

Filter by minimum amount total spent by a fan. Must use bracket syntax: filter[total_spent]=100 — the dot form (filter.total_spent=100) is rejected with a 422, because PHP rewrites it to filter_total_spent and the filter could not be applied. Must be at least 0.

filter.tipsinteger

Filter by minimum tips. Must use bracket syntax: filter[tips]=100 — the dot form (filter.tips=100) is rejected with a 422, because PHP rewrites it to filter_tips and the filter could not be applied. Must be at least 0.

filter.durationinteger

Filter by minimum subscription duration in months. Must use bracket syntax: filter[duration]=1 — the dot form (filter.duration=1) is rejected with a 422, because PHP rewrites it to filter_duration and the filter could not be applied. Must be at least 0.

filter.inactiveinteger

Filter by how long a fan has been unsubscribed. Available only for expired fans (type=expired). Use bracket syntax, e.g. filter[inactive]=3. Cannot be combined with filter[max_total_spent]. Must be at least 0.

Example:3
filter.max_total_spentnumber

Filter by maximum amount total spent by a fan — use filter[max_total_spent]=0 to isolate fans who have never spent. Combine with filter[total_spent] for a range. Must use bracket syntax: filter[max_total_spent]=0 — the dot form is rejected with a 422, because PHP rewrites it to filter_max_total_spent and the filter could not be applied.

OnlyFans itself has no maximum-spend filter, so this one is resolved against OnlyFansAPI's own fan index instead of being proxied. The fan objects in data.list are still fetched live from OnlyFans and are re-checked against your filters before being returned, but only fans we have already indexed for this account can appear. Each response reports its own coverage under data._source; when data._source.is_complete is false a full-base backfill is queued automatically, so retry later for a complete answer.

data._source.omitted_from_page counts fans that matched your filters but which OnlyFans returned no usable data for on that page (a deleted account, or a partial response). They are left out of data.list and not revisited later in the same walk, so a non-zero value means that page was short — start a fresh walk to retry them. Cannot be combined with filter[online]. Must be at least 0.

querystring nullable

Search within fan name/username.

Response

Example response

{
  "data": {
    "list": [
      {
        "view": "x",
        "avatar": "https://public.onlyfans.com/files/i/i2/i25/.../123/avatar.jpg",
        "avatarThumbs": {
          "c50": "https://thumbs.onlyfans.com/public/files/thumbs/c50/i/i2/i25/.../123/avatar.jpg",
          "c144": "https://thumbs.onlyfans.com/public/files/thumbs/c144/i/i2/i25/.../123/avatar.jpg"
        },
        "header": "https://public.onlyfans.com/files/c/cs/cse/.../123/header_image.jpg",
        "headerSize": {
          "width": 4386,
          "height": 1224
        },
        "headerThumbs": {
          "w480": "https://thumbs.onlyfans.com/public/files/thumbs/w480/c/cs/cse/.../123/header_image.jpg",
          "w760": "https://thumbs.onlyfans.com/public/files/thumbs/w760/c/cs/cse/.../123/header_image.jpg"
        },
        "id": 123,
        "name": "name",
        "username": "username",
        "canLookStory": true,
        "canCommentStory": true,
        "hasNotViewedStory": true,
        "isVerified": true,
        "canPayInternal": true,
        "hasScheduledStream": false,
        "hasStream": false,
        "hasStories": true,
        "tipsEnabled": true,
        "tipsTextEnabled": true,
        "tipsMin": 5,
        "tipsMinInternal": 1,
        "tipsMax": 200,
        "canEarn": true,
        "canAddSubscriber": true,
        "subscribePrice": 12.99,
        "subscriptionBundles": [
          {
            "id": 123,
            "discount": 50,
            "duration": 3,
            "price": 19.49,
            "canBuy": true
          }
        ],
        "displayName": "",
        "notice": "",
        "isPaywallRequired": true,
        "isRestricted": false,
        "canRestrict": true,
        "subscribedBy": true,
        "subscribedByExpire": false,
        "subscribedByExpireDate": "2025-01-01T00:00:00+00:00",
        "subscribedByAutoprolong": false,
        "subscribedIsExpiredNow": false,
        "currentSubscribePrice": 0,
        "subscribedOn": null,
        "subscribedOnExpiredNow": true,
        "subscribedOnDuration": "7 days",
        "listsStates": [
          {
            "id": "following",
            "type": "following",
            "name": "Following",
            "hasUser": true,
            "canAddUser": false,
            "cannotAddUserReason": "ALREADY_EXISTS"
          },
          {
            "id": "fans",
            "type": "fans",
            "name": "Fans",
            "hasUser": false,
            "canAddUser": false,
            "cannotAddUserReason": null
          },
          {
            "id": "recent",
            "type": "recent",
            "name": "Recent (last 24 hours)",
            "hasUser": false,
            "canAddUser": false,
            "cannotAddUserReason": "SYSTEM_LIST"
          },
          {
            "id": "tagged",
            "type": "tagged",
            "name": "Tagged",
            "hasUser": true,
            "canAddUser": false,
            "cannotAddUserReason": "ALREADY_EXISTS"
          },
          {
            "id": "friends",
            "type": "friends",
            "name": "Friends",
            "hasUser": false,
            "canAddUser": true,
            "cannotAddUserReason": null
          },
          {
            "id": "muted",
            "type": "muted",
            "name": "Muted",
            "hasUser": false,
            "canAddUser": true,
            "cannotAddUserReason": null
          }
        ],
        "canReport": true,
        "canReceiveChatMessage": true,
        "hideChat": false,
        "lastSeen": "2025-01-01T00:00:00+00:00",
        "isPerformer": true,
        "isRealPerformer": true,
        "subscribedByData": {
          "price": 0,
          "newPrice": 0,
          "regularPrice": 12.99,
          "subscribePrice": 12.99,
          "discountPercent": 0,
          "discountPeriod": 1,
          "subscribeAt": "2025-01-01T00:00:00+00:00",
          "expiredAt": "2025-01-01T00:00:00+00:00",
          "renewedAt": null,
          "discountFinishedAt": null,
          "discountStartedAt": null,
          "status": "Set to Expire",
          "isMuted": false,
          "unsubscribeReason": "No reason given",
          "duration": "2 months",
          "showPostsInFeed": true,
          "subscribes": [
            {
              "id": 123,
              "userId": 123,
              "subscriberId": 123,
              "date": "2025-01-01T00:00:00+00:00",
              "duration": 360,
              "startDate": "2025-01-01T00:00:00+00:00",
              "expireDate": "2025-01-01T00:00:00+00:00",
              "cancelDate": null,
              "price": 0,
              "regularPrice": 12.99,
              "discount": 0,
              "earningId": 0,
              "action": "subscribe",
              "type": "trial",
              "offerStart": "2025-01-01T00:00:00+00:00",
              "offerEnd": null,
              "isCurrent": true
            }
          ],
          "hasActivePaidSubscriptions": false
        },
        "subscribedOnData": {
          "price": 0,
          "newPrice": 0,
          "regularPrice": 0,
          "subscribePrice": 0,
          "discountPercent": 0,
          "discountPeriod": 1,
          "subscribeAt": "2025-01-01T00:00:00+00:00",
          "expiredAt": "2025-01-01T00:00:00+00:00",
          "renewedAt": null,
          "discountFinishedAt": null,
          "discountStartedAt": null,
          "status": null,
          "isMuted": false,
          "unsubscribeReason": "No reason given",
          "duration": "7 days",
          "tipsSumm": 0,
          "subscribesSumm": 0,
          "messagesSumm": 0,
          "postsSumm": 0,
          "streamsSumm": 0,
          "totalSumm": 0,
          "lastActivity": "2025-01-01T00:00:00+00:00",
          "recommendations": 0,
          "subscribes": [],
          "hasActivePaidSubscriptions": false
        },
        "canTrialSend": false,
        "isBlocked": false,
        "promoOffers": [],
        "canUnsubscribe": true,
        "isPendingAutoprolong": false
      }
    ],
    "hasMore": true
  },
  "_pagination": {
    "next_page": null
  },
  "_meta": {
    "_credits": {
      "used": 1,
      "balance": 999999838,
      "note": "Always"
    },
    "_cache": {
      "is_cached": false,
      "note": "Cache disabled for this endpoint"
    },
    "_rate_limits": {
      "limit_minute": 10000000,
      "limit_day": 50000,
      "remaining_minute": 9999999,
      "remaining_day": 49996
    }
  }
}

Changes

  • b3968f1bc1f0Revision changes
    • info

      added the new optional query request parameter filter.inactive

    • info

      added the new optional query request parameter filter.max_total_spent

  • 93a6dfdeeb67Revision changes
    • breaking

      the query request parameter filter.online was restricted to a list of enum values

    • breaking

      the query request parameter type was restricted to a list of enum values

    • breaking

      for the query request parameter filter.duration, the type changed from string to integer

    • breaking

      for the query request parameter filter.online, the type changed from string to integer

    • breaking

      for the query request parameter filter.tips, the type changed from string to integer

    • breaking

      for the query request parameter filter.total_spent, the type changed from string to integer

    • breaking

      for the query request parameter limit, the type changed from string to integer

    • breaking

      for the query request parameter offset, the type changed from string to integer

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property //// became nullable for the status

    • breaking

      the response property //// became nullable for the status

    • breaking

      the response property //// became nullable for the status

    • breaking

      the response property ////// became nullable for the status

    • breaking

      the response property ////// became nullable for the status

    • breaking

      the response property /// became nullable for the status

    • breaking

      the response property //// became nullable for the status

    • breaking

      the response property //// became nullable for the status

    • breaking

      the response property //// became nullable for the status

    • breaking

      the response property //// became nullable for the status

    • info

      added the new optional query request parameter query

    • info

      added the new enum value 0.00 to the query request parameter filter.online

    • info

      added the new enum value 1.00 to the query request parameter filter.online

    • info

      added the new enum value active to the query request parameter type

    • info

      added the new enum value all to the query request parameter type

    • info

      added the new enum value expired to the query request parameter type