List goal phases

Returns every bulk, cut, and maintenance phase (newest first) with planned vs actual weekly rate of weight change, the open phase, and a maintenance-calorie estimate from the caller’s own intake and weigh-ins (null until there are 10+ logged days across two weeks).

GET/api/phases

Authorization

__Secure-better-auth.session_tokenAPI key · cookierequired

Better Auth session. Signing in (Google or email magic link) sets an HttpOnly session cookie that scopes every request to that account. The web app and CLI use this; agents use the OAuth 2.1 flow of the MCP server.

AuthorizationBearer token · headerrequired

Personal API key sent as Authorization: Bearer skcal_…. Create and scope keys in the app under your profile → API keys. Keys default to full access; a scoped key is limited to its granted resource:action permissions and cannot manage other keys.

Query parameters

datestring<date>

The caller's local calendar day (YYYY-MM-DD), the default start or end day. Defaults to the server's UTC date.

Responses

200

The caller's phases with progress and the maintenance estimate.

activePhase | nullrequired

The open phase, if any.

Show properties

One of:

Phase

idstring<uuid>required

Phase identifier.

kindstringrequired

Phase type.

Allowed:bulkcutmaintain

startDatestring<date>required

First day.

plannedEndDatestring<date> | nullrequired

Planned last day.

endedDatestring<date> | nullrequired

Day it ended; null while it's the open phase.

activebooleanrequired

True for the open phase.

startWeightLbnumber | nullrequired

Bodyweight at the start, in pounds.

goalWeightLbnumber | nullrequired

Goal bodyweight in pounds.

ratePctPerWeeknumber | nullrequired

Planned weekly change, percent of bodyweight.

dailyKcalTargetinteger | nullrequired

The phase's daily calorie target.

proteinTargetGinteger | nullrequired

The phase's daily protein target in grams.

notestring | nullrequired

Free-text note.

progressPhaseProgressrequired

Planned vs actual rate of change, from a least-squares fit over the phase's weigh-ins.

Show properties

weeksElapsednumberrequired

Weeks since the start (to the end, for a closed phase).

weeksPlannednumber | nullrequired

Planned length in weeks.

latestWeightLbnumber | nullrequired

Latest weigh-in within the phase, in pounds.

changeLbnumber | nullrequired

Change since the start, in pounds.

plannedLbPerWeeknumber | nullrequired

Planned weekly change in pounds.

actualLbPerWeeknumber | nullrequired

Actual weekly change in pounds (null before a week of weigh-ins).

actualPctPerWeeknumber | nullrequired

Actual weekly change as a percent of start weight.

statusstringrequired

Whether the actual rate is within a third of the plan.

Allowed:on_tracktoo_fasttoo_slownot_enough_data

null

null

phasesPhase[]required

Every phase, newest first.

Show properties

Array of Phase

idstring<uuid>required

Phase identifier.

kindstringrequired

Phase type.

Allowed:bulkcutmaintain

startDatestring<date>required

First day.

plannedEndDatestring<date> | nullrequired

Planned last day.

endedDatestring<date> | nullrequired

Day it ended; null while it's the open phase.

activebooleanrequired

True for the open phase.

startWeightLbnumber | nullrequired

Bodyweight at the start, in pounds.

goalWeightLbnumber | nullrequired

Goal bodyweight in pounds.

ratePctPerWeeknumber | nullrequired

Planned weekly change, percent of bodyweight.

dailyKcalTargetinteger | nullrequired

The phase's daily calorie target.

proteinTargetGinteger | nullrequired

The phase's daily protein target in grams.

notestring | nullrequired

Free-text note.

progressPhaseProgressrequired

Planned vs actual rate of change, from a least-squares fit over the phase's weigh-ins.

Show properties

weeksElapsednumberrequired

Weeks since the start (to the end, for a closed phase).

weeksPlannednumber | nullrequired

Planned length in weeks.

latestWeightLbnumber | nullrequired

Latest weigh-in within the phase, in pounds.

changeLbnumber | nullrequired

Change since the start, in pounds.

plannedLbPerWeeknumber | nullrequired

Planned weekly change in pounds.

actualLbPerWeeknumber | nullrequired

Actual weekly change in pounds (null before a week of weigh-ins).

actualPctPerWeeknumber | nullrequired

Actual weekly change as a percent of start weight.

statusstringrequired

Whether the actual rate is within a third of the plan.

Allowed:on_tracktoo_fasttoo_slownot_enough_data

maintenanceMaintenanceEstimate | nullrequired

Maintenance calories estimated from the last 28 days of logged intake and weigh-ins.

Show properties

One of:

MaintenanceEstimate

kcalintegerrequired

Estimated daily maintenance calories.

daysintegerrequired

Logged days the estimate used.

null

null

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Parameters

datequeryThe caller's local calendar day (YYYY-MM-DD), the default start or end day. Defaults to the server's UTC date.

Request

curl -X GET 'https://app.skcal.fit/api/phases' \
  -H 'Cookie: __Secure-better-auth.session_token=YOUR_API_KEY' \
  -H 'Accept: application/json'

const response = await fetch("https://app.skcal.fit/api/phases", {
  method: "GET",
  headers: {
    "Cookie": "__Secure-better-auth.session_token=YOUR_API_KEY",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://app.skcal.fit/api/phases",
    headers={
        "Cookie": "__Secure-better-auth.session_token=YOUR_API_KEY",
        "Accept": "application/json"
    },
)

Response

{
  "active": null,
  "phases": [],
  "maintenance": {
    "kcal": 2650,
    "days": 24
  }
}