Reach

List Promotions

Returns the history of subscription promotions (discounted-price offers + free-trial bundles) the creator has run. Filterable by createdAt window. For aggregate promo earnings + a monthly chart, use Earnings Overview with by=promo. Requires permission api_reach_list_promotions.

https://public-api.fansmetric.com

GET/v1/{account_id}/reach/promotions

API keyBearer

Authorization

default

AuthorizationBearer <token>

Send your FansMetric API key as a Bearer token in the Authorization header.

In: header

Path Parameters

account_id*integer
OnlyFans numeric account ID.

Query Parameters

limitinteger
Page size. Default 10. Min 1, max 100.
offsetinteger
Rows to skip.
start_datestring
Lower bound on createdAt. Default 2 years ago, UTC.
end_datestring
Upper bound on createdAt. Default end of today, UTC.

Response Fields

data.items[].idinteger
Promotion ID. Pass to /reach/promotions/{promo_id}/subscribers for the claim list.
data.items[].messagestring
Promo description shown to fans (HTML allowed; often empty).
data.items[].rawMessagestring
Plain-text version of message.
data.items[].pricenumber
Discounted subscription price during the promo.
data.items[].typestring
Audience scope. Observed: all, expired. Other values may exist (new, current, …).
data.items[].canClaimboolean
true while the promo is still claimable.
data.items[].claimsCountinteger
Number of fans who claimed/subscribed via this promo.
data.items[].subscribeDaysinteger
Subscribe-days bonus. 0 when the promo doesn't extend the term.
data.items[].createdAtstring
ISO 8601 — when the promo was created.
data.items[].finishedAtstring
ISO 8601 — when the promo expired/will expire.
data.items[].isFinishedboolean
true once finishedAt has passed.
data.hasMoreboolean
Whether more pages are available.
dataobject | array
Endpoint-specific payload. See the fields below for this route.
_pagination.next_pagestring
Relative URL for the next page, with the cursor or offset already applied. Append it to the API base URL and send it as-is. Omitted entirely on the last page.
_meta._credits.usedinteger
Credits consumed by this request (currently always 1).
_meta._rate_limits.limit_minuteinteger
Maximum requests per minute for the organization.
_meta._rate_limits.remaining_minuteinteger
Remaining requests in the current minute window.
_meta._rate_limits.limit_dayinteger
Maximum requests per day for the organization.
_meta._rate_limits.remaining_dayinteger
Remaining requests in the current day window.

Field	Type	Description
data.items[].id	integer	Promotion ID. Pass to `/reach/promotions/{promo_id}/subscribers` for the claim list.
data.items[].message	string	Promo description shown to fans (HTML allowed; often empty).
data.items[].rawMessage	string	Plain-text version of `message`.
data.items[].price	number	Discounted subscription price during the promo.
data.items[].type	string	Audience scope. Observed: `all`, `expired`. Other values may exist (`new`, `current`, …).
data.items[].canClaim	boolean	`true` while the promo is still claimable.
data.items[].claimsCount	integer	Number of fans who claimed/subscribed via this promo.
data.items[].subscribeDays	integer	Subscribe-days bonus. `0` when the promo doesn't extend the term.
data.items[].createdAt	string	ISO 8601 — when the promo was created.
data.items[].finishedAt	string	ISO 8601 — when the promo expired/will expire.
data.items[].isFinished	boolean	`true` once `finishedAt` has passed.
data.hasMore	boolean	Whether more pages are available.
data	object \| array	Endpoint-specific payload. See the fields below for this route.
_pagination.next_page	string	Relative URL for the next page, with the cursor or offset already applied. Append it to the API base URL and send it as-is. Omitted entirely on the last page.
_meta._credits.used	integer	Credits consumed by this request (currently always `1`).
_meta._rate_limits.limit_minute	integer	Maximum requests per minute for the organization.
_meta._rate_limits.remaining_minute	integer	Remaining requests in the current minute window.
_meta._rate_limits.limit_day	integer	Maximum requests per day for the organization.
_meta._rate_limits.remaining_day	integer	Remaining requests in the current day window.

curl --request GET "https://public-api.fansmetric.com/v1/100000001/reach/promotions?limit=20&offset=0&start_date=2026-01-01%2000%3A00%3A00" \
  --header "Authorization: Bearer YOUR_API_KEY"

Response

200

{"data":{"hasMore":true
"items":[0:{"id":44934374
"message":"Half off your first month!"
"rawMessage":"Half off your first month!"
"hasRelatedPromo":false
"price":4
"type":"all"
"canClaim":false
"claimsCount":3
"subscribeCounts":null
"subscribeDays":0
"createdAt":"2025-02-21T05:53:48+00:00"
"finishedAt":"2025-02-28T05:53:48+00:00"
"isFinished":true
}
]
}
"_pagination":{"next_page":"/v1/100000002/reach/promotions?limit=10&offset=10"
}
"_meta":{"_credits":{"used":1
}
"_rate_limits":{"limit_minute":1000
"remaining_minute":999
"limit_day":50000
"remaining_day":49999
}
}
}

Get Profile Visitors Chart

List Promotion Subscribers