Skip to main content
Read workspace reports, statistics, comments, commits, and billing from your scripts, pipelines, and coding agents. The API is read-only: every endpoint is a GET request that returns JSON, and none of them run agents, change settings, or incur usage charges. To run the Macroscope agent from an HTTP request, see Webhooks.
The Macroscope API is in beta. We’d love to hear your feedback as we improve it. Send questions, suggestions, or issues to support@macroscope.com.

​
Create an API key

Create and manage keys under Settings → API. Only workspace admins can create API keys. Each key has read-only access to supported data across the whole workspace.
  1. Select Create API key.
  2. Enter a Name and choose when the key expires under Expires after. The default is 90 days, and the maximum is one year.
  3. Acknowledge the key’s workspace-wide read coverage, then select Create key.
  4. Copy the key and save it securely before closing the dialog. The key is shown only once.

​
Manage keys

Use Rotate to create a replacement key. Update your scripts to use the replacement, then Revoke the old key. Rotation does not revoke the old key for you. Revocation takes effect on the next request and cannot be undone. Applications using it will lose access.

​
Authentication

Set MACROSCOPE_API_KEY to your key in your script’s environment or secret manager. Send it as a bearer token in the Authorization header with each request:
Keys are scoped to a single workspace and do not inherit the creator’s permissions. Do not pass keys in URLs or query parameters. The API tab includes an example request for your workspace. Use it to check your setup.

​
Base URL

All endpoint paths are scoped to a workspace:
To find an organization’s ID: gh api orgs/YOUR_ORG --jq .id

​
Example request

​
Endpoints

Paths are relative to /workspaces/{workspaceType}/{workspaceId}.

​
Conventions

  • Dates are RFC 3339 timestamps (2026-10-01T00:00:00Z). URL-encode offsets such as +05:30. Defaults and inclusive/exclusive boundaries differ by endpoint. Reporting defaults can fall back to the preceding period; billing intervals and code-review statistics require dates. Comments default to the last 90 days, while commits have no date bounds unless supplied.
  • Money and large integers are strings, e.g. {"amount": "120.50", "currency": "USD"} and "commitCount": "42".
  • Percentages use two formats: percentDelta: 25 means 25%; rates such as addressedRate: 0.75 mean 75%.
  • Time values (coding time, engineering output) are estimated person-minutes, not elapsed time.
  • Missing fields are not errors. Empty lists, false, and 0 are omitted. A missing optional field, such as a balance, means the value is unavailable, not zero. When historyUpdating or shippedNotReady is true, results are still being processed.

​
Pagination

List areas, List billing meter summaries, List agent credit usage, List code review comments and List commits are paginated. Set pageSize (1 to 200, default 50), then pass nextPageToken as pageToken until it is absent, even when the page is short or empty. Repeat the original filters; pageSize may change. Tokens are bound to the workspace, operation and filters and expire after 24 hours; if a token is rejected (400), restart without it. Results are live, not a consistent snapshot.

​
Permissions and scope

Every endpoint requires workspace Read. Contributor statistics, coding-time statistics and team statistics additionally require Productivity. Report productivity insights and commit estimates are omitted without that permission. Code-review statistics, comments and commits authorize the selected repositories. Reports and productivity aggregates are workspace-wide and can include historical activity from repositories no longer accessible. Billing totals include excluded/deleted repositories and usage without repository attribution; repository restrictions do not reduce those amounts. API keys never inherit the creator’s Admin grant and can address only their bound workspace. Billing reads require workspace Read, including detailed usage and billing status.

​
Errors

Errors return an HTTP status and a JSON body:
An X-Request-ID header is returned when the request reaches the API handler. Include it in support requests when available.

​
Limits

Requests have a 55-second server timeout. Rate limits apply per key and per workspace. Responses with quota metadata include RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until reset); throttled requests also include Retry-After. Successful quota checks report the workspace budget, while a 429 reports the budget that rejected the request. Earlier authentication or routing failures and unavailable quota checks may not have these headers. Team listings return complete results without pagination or truncation. If a response is too large to return, the request fails with 429 and no partial results or continuation token; retrying unchanged does not resolve it.