RelayRunner docs: RelayRunner API Page: https://relayrunner.app/docs/reference/api Markdown: https://relayrunner.app/docs/reference/api.md All pages: https://relayrunner.app/docs/llms.txt Other pages (Markdown): - Changelog: https://relayrunner.app/docs/changelog.md - CLI changelog: https://relayrunner.app/docs/changelog/cli.md - CI traces in your observability tool: https://relayrunner.app/docs/changelog/opentelemetry-traces.md - Platform changelog: https://relayrunner.app/docs/changelog/platform.md - Retries, queueing and provider usage: https://relayrunner.app/docs/changelog/retries-queueing-and-provider-usage.md - Optimized checks: https://relayrunner.app/docs/concepts/optimized-checks.md - Principles: https://relayrunner.app/docs/concepts/principles.md - Routing: https://relayrunner.app/docs/concepts/routing.md - Runner order: https://relayrunner.app/docs/concepts/runner-order.md - Add a provider: https://relayrunner.app/docs/contribute/add-provider.md - Feedback: https://relayrunner.app/docs/contribute/feedback.md - Activity and history: https://relayrunner.app/docs/dashboard/activity.md - Performance: https://relayrunner.app/docs/dashboard/performance.md - Remove RelayRunner: https://relayrunner.app/docs/dashboard/remove.md - Signals: https://relayrunner.app/docs/dashboard/signals.md - Telemetry: https://relayrunner.app/docs/dashboard/telemetry.md - Usage and savings: https://relayrunner.app/docs/dashboard/usage.md - Workspaces and members: https://relayrunner.app/docs/dashboard/workspaces.md - Set up with an agent: https://relayrunner.app/docs/get-started/agents.md - How it works with GitHub Actions: https://relayrunner.app/docs/get-started/github-actions.md - Install the CLI: https://relayrunner.app/docs/get-started/install.md - Move your workflows over: https://relayrunner.app/docs/get-started/move-over.md - Route GitHub Actions jobs to any runner: https://relayrunner.app/docs/get-started/overview.md - Quickstart: https://relayrunner.app/docs/get-started/quickstart.md - Keep up with coding agents: https://relayrunner.app/docs/guides/agent-surge.md - Run CI on your laptop while you work: https://relayrunner.app/docs/guides/laptop-ci.md - macOS and iOS builds on your Mac: https://relayrunner.app/docs/guides/mac-builds.md - Spend controls: https://relayrunner.app/docs/guides/spend-controls.md - Share your team's machines: https://relayrunner.app/docs/guides/team-machines.md - RelayRunner API: https://relayrunner.app/docs/reference/api.md (this page) - CLI: https://relayrunner.app/docs/reference/cli.md - Errors: https://relayrunner.app/docs/reference/errors.md - FAQ: https://relayrunner.app/docs/reference/faq.md - GitHub App: https://relayrunner.app/docs/reference/github-app.md - Runner labels: https://relayrunner.app/docs/reference/labels.md - MCP server: https://relayrunner.app/docs/reference/mcp.md - Data and privacy: https://relayrunner.app/docs/reference/privacy.md - relay.yml inputs: https://relayrunner.app/docs/reference/relay-inputs.md - Repo config: https://relayrunner.app/docs/reference/repo-config.md - Security: https://relayrunner.app/docs/reference/security.md - Troubleshooting: https://relayrunner.app/docs/reference/troubleshooting.md - GitHub-hosted: https://relayrunner.app/docs/runners/github.md - Hosted providers: https://relayrunner.app/docs/runners/hosted.md - Providers: https://relayrunner.app/docs/runners/providers.md - Your machines: https://relayrunner.app/docs/runners/self-hosted.md --- # RelayRunner API > Read your workspace's runners, runs, routing and usage over HTTP. The RelayRunner API is the read-only HTTP API behind the [MCP server](/docs/reference/mcp). > **Connecting an AI agent?:** Use the [MCP server](/docs/reference/mcp) instead. Claude, Cursor, VS Code and other MCP clients sign in on their own and get these routes as tools. Call the API directly only if you're writing your own OAuth client. ```text https://api.relayrunner.app/api ``` [API routes](/docs/reference/api/routes) lists every route with its parameters and responses, and you can try them there. The [OpenAPI spec](/openapi.json) has the same in JSON. ## Sign in The API uses OAuth 2.1 with PKCE and the `workspace:read` scope. Clients can register themselves, and the authorization server publishes its endpoints at `https://app.relayrunner.app/.well-known/oauth-authorization-server/api/auth`. While signing in, you pick which workspaces the token may read. Send the access token as `Authorization: Bearer `. Tokens last 15 minutes; use the refresh token for a new one. When a token covers more than one workspace, name the one you're asking about in the `x-relayrunner-workspace` header. ## Routes | Route | What it returns | | -------------------------------------------------------- | ---------------------------------------------------------------------- | | `GET /me` | You and the workspaces the token may read | | `GET /workspaces/current` | One workspace, your role and its GitHub accounts | | `GET /workspaces/{id}/runner-order` | The providers jobs are tried on, in order | | `GET /workspaces/{id}/router-setup` | Recent workflows and how many of their runs were routed | | `GET /machines` | Runners, their status, labels, pause state and current job | | `GET /runs` | Workflow runs from the last 14 days | | `GET /runs/{repositoryId}/{runId}/{runAttempt}/jobs` | One run's jobs and where each ran | | `GET /runs/{repositoryId}/{runId}/{runAttempt}/failures` | Why a run's jobs failed, with the end of each log | | `GET /activity` | The activity log, including where each job was routed and why | | `GET /usage`, `/usage/checks`, `/usage/actions` | Short jobs and round-up cost, optimized check savings, Actions minutes | | `GET /job-times` | Typical job durations per runner | | `GET /signals` | What's making CI slow, costly or busier than it needs to be | | `POST /feedback` | Reports a bug, confusing result or missing feature to the team | A failed request answers with a code and a message, such as `{"error": {"code": "INVALID_REQUEST", "message": "The request isn't valid."}}`. [Errors](/docs/reference/errors) lists every code. ## Rate limit Each person's connection can make 300 requests a minute, counting requests from the MCP server too. Past that, the API answers `429` with the `RATE_LIMITED` code and a `Retry-After` header.