Skip to main content

Get Current Recovery Score

This example will use the Fetch API to make an HTTP request to WHOOP's server.

Prerequisites​

  • Access Token: The token received after completing the OAuth 2.0 flow. Your app must pass the Access Token as a Bearer token in the Authorization header.
  • The Access Token is granted permission to read:cycles and read:recovery OAuth scopes.

Overview​

The process of getting a user's current recovery score requires two steps:

  • Get the user's current Cycle. (API Docs)
  • Get the user's Recovery for the current Cycle if one exists. (API Docs)

These two steps are required because every Cycle is not guaranteed to have a Recovery score. For example, the user may not have worn their WHOOP the previous day. In this scenario, the Recovery score will be missing for the Cycle.

Get the User's Current Cycle​

Let's start by getting the current Cycle. The Cycle Collection is sorted by time in descending order, so making a request with limit=1 will give us the latest Cycle.

const accessToken = "__ACCESS_TOKEN_FOR_USER__";

query = new URLSearchParams({
  limit: "1",
});

We will append those parameters as query param values to our GET request.

const getCurrentCycle = async (accessToken, query) => {
  const uri = `https://api.prod.whoop.com/developer/v1/cycle?${query}`;

  const cycleResponse = await fetch(uri, {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });

  if (cycleResponse.status === 200) {
    return cycleResponse.json();
  } else {
    throw new Error(`Received ${cycleResponse.status} status from Whoop`);
  }
};

Response​

The response will include an array of Cycles, which should have precisely one if the user has at least one Cycle (new users may not have a Cycle yet, so check there is at least one in the array). You will need the cycle_id from the latest cycle for the next step.

Array of objects (Cycle) [ items ]

The collection of records in this page.

next_token
string

A token that can be used on the next request to access the next page of records. If the token is not present, there are no more records in the collection.

{
  • "records": [
    ],
  • "next_token": "MTIzOjEyMzEyMw"
}

Get Recovery for Cycle​

With the latest Cycle, we can now get the Recovery score for the Cycle if one exists. Before using the Recovery score, there are a few things you should consider:

  • Not every Cycle has a Recovery - the user may not have worn their strap the previous day.
  • New users may be calibrating. New users require calibration before the Recovery score is relevant to them. The calibration period lasts a few days for new users. You can use the field user_calibrating to check if the user is still in the calibration phase.
  • WHOOP may not be able to score every Recovery - you should check if the score_state is SCORED. If the score_state is PENDING_SCORE, you will need to check back later. If the score_state is UNSCORABLE, a Recovery Score cannot be calculated by WHOOP for this user's Cycle.
const getRecoveryForCycle: = async (accessToken, cycleId) => {
    const uri = `https://api.prod.whoop.com/developer/v1/cycle/${cycleId}/recovery`

    const recoveryResponse = await fetch(uri, {
        headers: {
            Authorization: `Bearer ${accessToken}`,
        },
    })

    if (recoveryResponse.status === 200) {
        return recoveryResponse.json()
    } else if (recoveryResponse.status === 404) {
        return null
    } else {
        throw new Error(`Received ${recoveryResponse.status} status from Whoop`)
    }
}

Response​

Upon success, the API should return a 200 HTTP status or 404 if a Recovery does not exist for the current cycle. Remember not all Cycles will have a Recovery.

cycle_id
required
integer <int64>

The Recovery represents how recovered the user is for this physiological cycle

sleep_id
required
integer <int64>

ID of the Sleep associated with the Recovery

user_id
required
integer <int64>

The WHOOP User for the recovery

created_at
required
string <date-time>

The time the recovery was recorded in WHOOP

updated_at
required
string <date-time>

The time the recovery was last updated in WHOOP

score_state
required
string
Enum: "SCORED" "PENDING_SCORE" "UNSCORABLE"

SCORED means the recovery was scored and the measurement values will be present. PENDING_SCORE means WHOOP is currently evaluating the cycle. UNSCORABLE means this activity could not be scored for some reason - commonly because there is not enough user metric data for the time range.

object (RecoveryScore)

WHOOP's measurements and evaluation of the recovery. Only present if the Recovery State is SCORED

{
  • "cycle_id": 93845,
  • "sleep_id": 10235,
  • "user_id": 10129,
  • "created_at": "2022-04-24T11:25:44.774Z",
  • "updated_at": "2022-04-24T14:25:44.774Z",
  • "score_state": "SCORED",
  • "score": {
    }
}

Congratulations​

You have now received Recovery data for the current Cycle.