First call

Your first call costs nothing. It checks that your key works, and it tells you who you are for the API, what your key can do and how many credits you have left.

1. Call GET /me

Open Terminal (Mac) or Command Prompt (Windows 10 and later). Replace fd_live_xxxxxxxx with your key and run:

curl "https://api.fitdistance.io/api/partner/v1/me" -H "Authorization: Bearer fd_live_xxxxxxxx"

Keep the word Bearer, a space, then your whole key.

2. Read the response

Here is an excerpt, with made-up values:

{
  "coach": { "id": 42, "first_name": "Camille", "last_name": "Martin" },
  "tier": "maestro",
  "key": { "name": "Nightly sync", "scopes": ["students:read", "training:read"] },
  "credits": {
    "plan_remaining": 487,
    "plan_resets_at": "2026-11-01T00:00:00.000Z",
    "bonus_remaining": 0
  }
}

The full response has other fields, described in the reference. This call is free, but it counts toward the pace limit of your key.

If you get a 401 UNAUTHORIZED, the key is missing, unknown or revoked: copy it again in full. A 403 PLAN_NOT_ELIGIBLE means your plan does not include the API.

3. Make a billed call

Now list your students. The -i option also prints the headers of the response:

curl -i "https://api.fitdistance.io/api/partner/v1/students?limit=50" -H "Authorization: Bearer fd_live_xxxxxxxx"

This call returns up to 50 active students and costs one credit, debited before it runs. It needs the scope Students › Read (students:read). A refused parameter, such as limit=500, gives a 400 VALIDATION and also costs a credit. On an operation it is different: an argument that its schema refuses is refunded, and only the refusal of the operation itself stays billed. Here is an excerpt of the body:

{
  "data": [
    {
      "id": 1,
      "first_name": "Léa",
      "last_name": "Dupont",
      "contract_status": "ACTIVE",
      "updated_at": "2026-10-24T08:12:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

The students are in data. When has_more is true, more pages remain: pass next_cursor as cursor to read the next one.

4. Spot the credits in the headers

Every billed response carries two headers:

X-Credits-Remaining: 486
X-Credits-Plan-Resets-At: 2026-11-01T00:00:00.000Z

X-Credits-Remaining is the total you have left, included credits and reserve together. X-Credits-Plan-Resets-At is the date when the included credits are reset. GET /me does not return these headers: it gives the same figures in its body.

If you get a 403 SCOPE_MISSING, the key lacks the scope you need and details.scope names it. A 402 CREDITS_EXHAUSTED means you have no credit left. Neither costs a credit.

What next

Go to Write a script to read every page and write without duplicates, or to Keys and credits to learn what costs a credit.