mila-sarc

Fetching data from the SARC API

SARC serves a JSON API over HTTPS at https://sarc.mila.quebec. Everything below is plain HTTP — curl, requests, or any client will do; there is nothing to install.

Two families of endpoints matter:

Prefix	What it gives you	Response
/v0/…	Raw records: slurm jobs, job series (jobs + computed usage/waste/RGU columns), users, clusters, GPU→RGU table, health checks	JSON
/dash/metrics/…	Pre-aggregated dashboard data: job counts, RGU usage, metric distributions, per-user/per-cluster rollups	JSON

https://sarc.mila.quebec/dash/metrics itself is the human-facing dashboard (HTML) — worth opening in a browser to see what the JSON endpoints feed.

The parameters below are enough to query the API directly — go ahead and call it. If a call fails in a way this document doesn't explain, fetch https://sarc.mila.quebec/openapi.json (public, no token; interactive at /docs) — it's the authoritative description of what the server accepts.

Authentication

Every endpoint except /v0/health/list, /docs and /openapi.json requires a bearer token:

Authorization: Bearer $SARC_TOKEN

Three environment variables carry everything you need. Check them first — an unset SARC_TOKEN is the single most common reason requests come back 401 {"detail":"Authentication required"}:

test -n "$SARC_TOKEN" && echo "token: set" || echo "token: MISSING"
echo "user: ${SARC_USERNAME:-unset}  admin: ${SARC_IS_ADMIN:-0}"

If SARC_TOKEN is empty, stop and give the user the snippet below to paste into their ~/.bashrc (~/.zshrc works the same). Fill SARC_USERNAME in with your best guess from the conversation if you have one (usually [email protected]) — otherwise leave the placeholder. Don't try to work around a missing token.

# --- SARC ---------------------------------------------------------------
# API token. Open https://sarc.mila.quebec/token in a browser, sign in with
# your Mila Google account, and copy the "refresh_token" value from the JSON
# page you land on. It is long-lived: treat it like a password, and never
# commit it.
export SARC_TOKEN='paste-the-refresh_token-value-here'

# Your @mila.quebec address — how SARC identifies you.
export SARC_USERNAME='[email protected]'

# 1 if your SARC account has the admin capability, 0 otherwise.
# Leave it at 0 if you don't know; you'd know if you had it.
export SARC_IS_ADMIN=0
# ------------------------------------------------------------------------