Jog's advice API

Tokens

Calls take a Jog personal access token: Authorization: Bearer jog_pat_…. A token acts for one person and reads advice only, of their accounts. It reads nothing else on Jog: no money, settings, logs or other pages. Advice is for an account's owners for now.

• For an agent: POST https://usejog.com/api/device with {"name", "access": "advice", "org"} (org, an account's login, is optional: without it the token reads all the person's accounts). The person approves the code in their browser; a token for one account can be approved only by its owners. Poll POST /api/device/token with {"deviceCode"} every interval seconds until it answers key, handed over once. Until then it answers an error: authorization_pending (not approved yet), logins_busy_here (too many asks at once from that network: ask again after retryAfter seconds), busy (ask again in a few seconds), access_denied (declined) or expired_token (expired, or the key was already collected: ask for a new code). Asking for a code can also answer logins_busy or logins_busy_here, with retryAfter. Each approval makes a new token, which lasts 7 days; none replaces an older one, even of the same name, so revoke those no longer used.
• For CI: the person makes one at https://usejog.com/account/-/tokens, for all their accounts or one, for 7, 30 or 90 days. It is shown once.

Revoke a token there, or with POST https://usejog.com/api/key/revoke and the token itself. Jog keeps only a token's hash. Its text is jog_pat_, 64 hex digits and 8 of check: the first 4 bytes of the SHA-256 of the rest.

GET/api/orgs/{org}/advice

Every job's advice over the last 30 days. Send Jog-Route-Version: 3: this answer is at version 3, and a call naming an older version, or none, gets 409 updated. Query: goal (cost, balanced or speed; the account's own otherwise, balanced until it chooses) and until (the window's end, at most now, as 2026-10-24T23:36:10Z). Pass the first answer's window.end as until to every later read, of either route, so they all read the same window. A run Jog hears of late, or whose measure comes after its charge, can still join it: if two reads disagree about a job, read both again.

curl -G https://usejog.com/api/orgs/ACCOUNT/advice \
  -H "Authorization: Bearer $JOG_TOKEN" \
  -H "Jog-Route-Version: 3"

{
  "goal": "balanced",
  "jobs": [
    {
      "after": {},
      "before": {},
      "detail": "Its CPU stayed under half of 8 vCPUs in most runs.",
      "diskPeakBytes": 2147483648,
      "job": {},
      "kill": {},
      "killed": 12,
      "kind": "smaller",
      "largestKill": {},
      "lastRunAt": "2026-10-24T23:36:10Z",
      "limits": {},
      "loadUsec": [],
      "memoryGrowthBytes": 2147483648,
      "memoryP95Bytes": 2147483648,
      "memoryPeakBytes": 2147483648,
      "now": {},
      "reason": "cpu",
      "sample": {},
      "size": "jog-8vcpu",
      "sizeInName": false,
      "sizeMemoryPeakBytes": 2147483648,
      "title": "Smaller and about as fast",
      "to": "jog-4vcpu",
      "unmeasured": 12,
      "unwhole": 12
    }
  ],
  "now": "2026-10-24T23:36:10Z",
  "window": {
    "end": "2026-10-24T23:36:10Z",
    "start": "2026-10-24T23:36:10Z"
  }
}

GET/api/orgs/{org}/advice/runs

Every run in the window, on Jog or Jog Max, or one job's (repoId, workflowFile and job together), newest first, 1,000 a page. Send Jog-Route-Version: 2: this answer is at version 2, whose size can be Jog Max's, and a call naming an older version, or none, gets 409 updated. While next isn't null, ask again with beforeAt set to its at and beforeJobId to its jobId; the last page can be empty. Take the same until as the advice to read the same window. Each run: jobId, job, at, size, seconds, cost, counted (counted, not_passed, unmeasured), outcome (passed, failed, neither), cpuUsec, cpuPeakMillicpus, memoryPeakBytes, diskPeakBytes, ioReadBytes, ioWriteBytes, networkRxBytes, networkTxBytes, memoryKills. A job's passed and failed are counts of its runs' outcomes.

curl -G https://usejog.com/api/orgs/ACCOUNT/advice/runs \
  -H "Authorization: Bearer $JOG_TOKEN" \
  -H "Jog-Route-Version: 2"

{
  "next": {
    "at": "2026-10-24T23:36:10Z",
    "jobId": 31415926
  },
  "now": "2026-10-24T23:36:10Z",
  "runs": [
    {
      "at": "2026-10-24T23:36:10Z",
      "cost": 4180,
      "counted": "counted",
      "cpuPeakMillicpus": 12,
      "cpuUsec": 12,
      "diskPeakBytes": 2147483648,
      "ioReadBytes": 2147483648,
      "ioWriteBytes": 2147483648,
      "job": {},
      "jobId": 31415926,
      "loadUsec": [],
      "memoryKills": 12,
      "memoryPeakBytes": 2147483648,
      "networkRxBytes": 2147483648,
      "networkTxBytes": 2147483648,
      "outcome": "passed",
      "seconds": 12,
      "size": "jog-8vcpu"
    }
  ],
  "window": {
    "end": "2026-10-24T23:36:10Z",
    "start": "2026-10-24T23:36:10Z"
  }
}

Errors

{"error": code, "message": words}

The same runs always give the same advice under a goal.