Skip to content

notion.md

Latest commit

 

History

History
164 lines (124 loc) · 8.65 KB

notion.md

File metadata and controls

164 lines (124 loc) · 8.65 KB
Raw
summary Notion AI provider auth, usage endpoint, and allowance windows.
read_when
Adding or modifying the Notion AI provider
Debugging Notion cookie import or usage parsing
Explaining Notion AI setup

Notion AI Provider

The Notion AI provider tracks the Rolling (6-hour) and Monthly (billing period) usage allowance windows that Notion shows in Settings → Notion AI → Usage.

Notion begins enforcing the AI usage allowance on August 3, 2026. Before that date the same endpoint reports "enforcement": "preview" while still returning real usage numbers, so the gauges are accurate either way.

Unsupported integration: CodexBar uses Notion's internal, cookie-authenticated /api/v3 endpoints. These endpoints are not a supported public API and may change or break without notice.

Requirements

The usage allowance only exists on Business and Enterprise workspaces. Free, Plus, and personal workspaces make the endpoint answer {"status":"not_applicable"}, and CodexBar surfaces that as a clear provider error rather than an empty gauge.

Setup

Automatic (recommended)

  1. Sign in to Notion in a supported browser.
  2. Enable Notion AI in Settings → Providers.

The bundled Notion plugin runs on both engines. The host imports your browser session cookie automatically and sends it only to https://app.notion.com; the script sees an opaque session ID, never the cookie values. Within each profile, source domains rank as app.notion.com, www.notion.com, notion.com, www.notion.so, then notion.so. The import requires the token_v2 session cookie; a browser profile that has Notion cookies but no token_v2 is skipped rather than used for a request that would fail with 401.

Note: Automatic import follows the shared supported-browser order. Background refreshes only read Chromium cookies when the no-UI Keychain preflight confirms existing access; they never request a new permission. Use an explicit Refresh to authorize cookie decryption when needed, or use Manual mode. An explicit refresh permits at most one browser permission retry.

Validated sessions remain in the shared cookie cache. Background refreshes first reuse the existing owner-only notion-session.json token file, then the shared cache. If neither succeeds, browser reads remain subject to the shared access gate: background reads require existing prompt-free authorization, while explicit CLI cookie refreshes retain their acknowledged retry scope. A successful allowance fetch updates both stores; a 401 conditionally clears the rejected session without erasing a newer one. An interactive cookie refresh commits its replacement only after success, preserving both prior stores on failure.

Manual

Set Cookie source to Manual in the Notion AI provider settings, then paste one of:

  • The bare token_v2 value,
  • A Cookie: ... header value copied from a browser network request to app.notion.com, or
  • A full curl command captured from the Notion web app (all -H flags are parsed; only the Cookie header and a fixed set of safe request headers are forwarded).

To capture the cookie manually:

  1. Open app.notion.com in your browser.
  2. Open Developer Tools → Network tab.
  3. Open Settings → Notion AI → Usage and find a getCreditRateLimitStatus request.
  4. Right-click → Copy → Copy as cURL.
  5. Paste the full curl command into the Notion cookie field in CodexBar settings.

Workspace selection

Accounts that belong to more than one workspace default to the first workspace on a Business or Enterprise plan. To pin a specific one, set Workspace ID in the provider settings, or workspaceID on the notion entry in config.json. Both dashed and undashed UUID forms are accepted.

For accounts with many workspaces or members, discovery can exceed the plugin's 5 MiB response limit. If Workspace ID contains a valid UUID, CodexBar then requests allowances directly for that workspace. Email, account ID, workspace name, and plan are omitted for that refresh because discovery did not complete; normal-sized discovery still supplies them. Without a valid Workspace ID, the error asks you to configure one. The shared response limit remains unchanged, including for the allowance request.

Notion does not support a standalone environment variable or a --cookie CLI flag for this provider. The only manual paths are the Settings fields above and config.json.

Data Source

CodexBar sends two POST requests per refresh, both to https://app.notion.com:

  1. /api/v3/getSpaces — resolves the signed-in user (email, name) and the workspaces the account can see, including each workspace's plan_type and subscription_tier. This is what makes automatic workspace selection and the account identity line possible.
  2. /api/v3/getCreditRateLimitStatus with {"spaceId": "<uuid>"} — the allowance itself.

The rate-limit response looks like this:

{
  "status": "within_limit",
  "window": { "creditType": "basic_ai_credits", "scope": "per_user", "window": "6h", "used": 42.5, "limit": 100 },
  "resetsInSeconds": 12600,
  "billingPeriodWindow": {
    "creditType": "basic_ai_credits",
    "scope": "per_user",
    "cadence": "billing_period",
    "used": 18.0,
    "limit": 100,
    "periodEndMs": 1788000000000
  },
  "enforcement": "preview"
}

Mapping

CodexBar window Notion field Notes
Rolling (primary) window.used / window.limit window.window (6h) sets the window length; resetsInSeconds sets the reset time.
Monthly (secondary) billingPeriodWindow.used / .limit periodEndMs sets the reset time, and the window length is the calendar month ending there.
Identity getSpaces Account email, workspace name, and the capitalized subscription tier.

Usage is reported against the returned limit rather than assumed to be a percentage, so a future non-100 limit keeps working. Over-quota values are preserved rather than clamped; display clamping happens downstream. The plugin declares snapshotPolicy: {percent: "preserve-overage"} to retain this behavior on both engines.

Custom Agents and Workers are not covered by this allowance — Notion meters those with Notion credits (getAIUsageEligibilityV2), which this provider does not read.

Pace

The monthly card also shows a daily credit target from the reported remaining allowance and the local calendar days until reset, including today. This does not estimate credits consumed today; Notion does not report that breakdown. Hiding pace hides the target as well.

Both bars carry an expected-usage estimate on the card and in codexbar usage, reading n% in deficit when you are ahead of an even burn and n% in reserve when behind.

The monthly estimate needs a window length, and Notion reports only periodEndMs. The snapshot therefore carries the shared monthly sentinel, which is what makes the provider's ProviderPaceCapability match; resolution then substitutes the real calendar month ending at the reset — not a flat 30 days, which would misstate expected usage in February and in any 31-day cycle.

A nil length is not a safe alternative. UsagePace.weekly substitutes the caller's defaultWindowMinutes (7 days on every weekly path) rather than skipping the window, so a lengthless billing period would be scored against a week; the surfaces that do refuse a lengthless window drop it from pacing entirely instead. Every path that scores one of these windows — the card, the menu-bar pace token, predictive pace warnings, and the CLI — resolves the sentinel first, so they cannot disagree.

The rolling window is paced as a session window. Its length comes from the API's 6h token rather than being fixed, so only a window no longer than six hours is paced this way; anything longer is a billing period and goes through the reset-window path instead.

Status

Notion publishes a status page at https://status.notion.so/; CodexBar links to it but does not poll components.

Troubleshooting

  • "Notion AI usage allowance is not tracked for …" — the selected workspace is not on a Business or Enterprise plan. Set Workspace ID to a workspace that is.
  • "Notion session cookie is invalid or expired" — sign in to Notion again, or re-capture the manual cookie.
  • "No Notion cookies found" — the browser profile has no token_v2 cookie for Notion. Sign in, or switch to a manual cookie.
  • "Notion workspace discovery is too large" — set Workspace ID to the UUID of the Business or Enterprise workspace to monitor. You can find it in the spaceId body field of the getCreditRateLimitStatus request described in the Manual setup instructions.