list_referrals
List the friends affiliates brought in — how each arrived, whether they paid, and until when the affiliate earns on them. Read-only, paginated.
Read the referrals a programme has counted: to report on a campaign, to see which friends paid, or
to page only what happened since a report last ran. status is typed before the service sees it, and
since is an ISO 8601 instant; an unknown word or a malformed date is a VALIDATION_FAILED, never an
empty page.
Read-only. Never mutates anything. Nothing names a friend beyond their member id.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same actions as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project whose referrals to list.
statusstringoptionalOptional filter: "touched", "converted", "expired" or "rejected".
affiliate_idstringoptionalOptional affiliate UUID, to list one affiliate's referrals.
sincestringoptionalOptional ISO 8601 instant: only referrals whose friend arrived on or after it.
limitintegeroptionalMaximum referrals to return per page (1..100).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "3c4d5e6f-7081-4a2b-9c3d-4e5f6a7b8c9d", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "program_id": "6e2a7a4f-3b8c-4c21-9f6d-2a3b4c5d6e7f", "affiliate_id": "0b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b", "member_id": "b2c3d4e5-f6a7-4819-9b0c-1d2e3f4a5b6c", "source": "connector_link", "connector": "telegram", "status": "converted", "touched_at": "2026-10-08T11:00:00+00:00", "expires_at": "2026-11-07T11:00:00+00:00", "converted_at": "2026-10-09T14:20:00+00:00", "converted_subscription_id": "5d6e7f80-91a2-4b3c-8d4e-5f6a7b8c9d0e", "commission_ends_at": "2027-04-09T14:20:00+00:00", "created_at": "2026-10-08T11:00:00+00:00" } ], "meta": { "page": 1, "limit": 25, "total": 1, "has_more": false }}A referral is a touch until the friend pays
touched means the friend arrived and is counted for thirty days;
converted means their first payment settled and the affiliate earned;
expired means the window passed. The reward itself is a row of
list_referral_rewards.
source is portal_link, connector_link or code_at_checkout; connector names the
bot's platform on a connector link and is null otherwise. commission_ends_at is when the
affiliate stops earning on this friend on a programme with a period; null for life, for a
first-payment-only commission, or before conversion.
How it fails
VALIDATION_FAILEDstatus is not touched, converted, expired or rejected, or since is
RESOURCE_NOT_FOUNDunknown project_id, a project on another team, or one outside the token's
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-referral:view-any.
How is this guide?
Last updated on
list_referral_rewards
List the referral ledger — the days or money each settled payment earned, whose it is and where it stands. Read-only, paginated.
record_referral_payout
Record money the creator paid an affiliate outside Subscriby, so the ledger marks their oldest payable commissions as paid. Destructive. Emits referral.payout_recorded.