---
title: "Read your referral link, what it pays, the writers you brought in and the credits earned."
method: GET
path: "/referrals"
tags: ["Credits"]
---

# Read your referral link, what it pays, the writers you brought in and the credits earned.

`GET /referrals`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/referrals`
- Auth: HTTP bearer

The same read the Billing page's referral panel makes: `signupUrl` (the link to share, issued on first read), `rewards` (what each step pays you and the writer you bring on your track, the numbers the payout uses) and `rewardSentence` (the same as one sentence), `totalReferees` (writers brought in) and `paidConversions`, the credits earned (`peerLifetimeCredits` + `mentorLifetimeCredits`; a peer's quarter against `peerQuarterlyCap`), and `recentEvents`, each named in plain words (`label`, and `voidLabel` when it paid nothing). Read-only: nothing here pays or moves a credit. Scope: `credits:read`. Free.

## Response `200`

The referral program as the Billing page shows it.

- Referrals: The writer's referral program, as the Billing page's referral panel shows it.
  - `code` string, nullable, required: The writer's referral code.
  - `signupUrl` string, nullable, required: The link to share: a writer who signs up through it is theirs.
  - `isMentor` boolean, required: True on the mentor track (uncapped); false on the peer track.
  - `rewards` object[], required: What each step pays on this writer's track, the numbers the payout uses.
    - `trigger` 'FIRST_PROVISION' | 'PAID_UPGRADE', required
    - `when` string, required: When it pays, in words ("When they upgrade to a paid plan").
    - `you` integer, required: Studio Credits the writer earns.
    - `them` integer, required: Studio Credits the writer they brought earns.
  - `rewardSentence` string, required: The rewards as the one sentence the Billing page shows.
  - `peerLifetimeCredits` integer, required: Credits earned on the peer track, all time.
  - `peerQuarterlyCredits` integer, required: Credits earned on the peer track this quarter.
  - `peerQuarterlyCap` integer, required: The most a peer earns in one quarter.
  - `mentorLifetimeCredits` integer, required: Credits earned on the mentor track, all time.
  - `totalReferees` integer, required: People brought in.
  - `paidConversions` integer, required: Of those, how many upgraded to a paid plan.
  - `recentEvents` object[], required: The latest referral events, newest first (at most 12).
    - `id` string, required
    - `trigger` 'FIRST_PROVISION' | 'PAID_UPGRADE', required
    - `label` string, required: What the writer they brought did, in plain words.
    - `track` 'PEER' | 'MENTOR', required
    - `creditsToReferrer` integer, required
    - `refereeInitials` string, required: The writer they brought, as initials only.
    - `voidReason` string, nullable, required: Why it paid nothing, as a code; null when it paid.
    - `voidLabel` string, nullable, required: Why it paid nothing, in plain words; null when it paid.
    - `createdAt` string, date-time, required

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/86e084144cef?raw)