Skip to main content

​
Management API

The Runlayer platform provides a RESTful API for programmatic management of your organization’s MCP infrastructure. Key Capabilities:
  • Server Management: Create, update, and delete MCP servers
  • User Operations: Read user information and permissions
  • Audit Logs: Query activity history and security events
  • Analytics: Access usage metrics and insights

​
Coverage by Data Type

Use this table to decide which public surface to start from:
For interactive request/response schemas and a built-in API explorer, visit /docs on your hosted Runlayer instance. It lists the connector (server) and current-user endpoints. The agent endpoints are documented on this page.

​
Authentication

For personal or organization API keys, send the key in the x-runlayer-api-key header. Do not send API keys as bearer tokens. The base URL is your Runlayer instance with the /api/v1 prefix.
Responses are JSON. Standard HTTP status codes apply — 401 for a missing or invalid key, 403 when the key’s role lacks access to the endpoint.

​
Agent runs

Start an agent run from your own code, poll it, cancel it, and continue the conversation. Use a personal API key. The run executes as the key’s owner, with that person’s access and connected accounts, and needs an agent they can run. Organization API keys and agent account keys aren’t accepted here.
  • Agent ID: the UUID in the app URL (/agents/<agent-id>), or search with GET /api/v1/agents?query=.
  • Status: running until it ends as succeeded, failed or cancelled. Poll every 10 to 15 seconds. succeeded means the agent finished its turn; read output for what it said.
  • Continue a conversation: pass the id of a finished run you started as runId (camelCase). The new run picks up the same conversation.
  • Cancel: works while can_cancel is true. Otherwise you get 400 (“This run’s runtime does not support cancellation”). A run that already ended comes back unchanged. 409 means the cancel didn’t settle; read the run again before retrying.
  • Who can read a run: you can read runs you started. The agent’s owner and editors can read everyone’s. With workspace content redaction on, other people’s runs come back with input, output and error empty and is_redacted: true unless you’ve unlocked them. Their grouped_steps keep each step’s kind, tool, tokens and timing, with ***REDACTED*** in place of its text and error and no raw events or attachments.
  • Errors when starting: 400 empty input; 403 the agent isn’t shared with you or you can only view it; 404 no such agent; 429 the agent hit its run limit or cost budget.
  • No OTLP export of runs: agent runs aren’t sent to your OpenTelemetry collector. To get them into your own tooling, use the audit-log SIEM export (agent_run, agent_run_success and agent_run_failure events, plus tool_call* events that carry the run’s agent_id and run_id), the session SIEM export for full transcripts, or read each run from this API (duration, token counts, total_cost_usd, grouped_steps) and convert it yourself.
  • No callbacks yet: Runlayer doesn’t push completion events or heartbeats to your system, so poll. For progress updates, tell the agent to call your endpoint itself over HTTPS and allow that host in its network access policy.
To start runs from a system that shouldn’t hold a person’s key, use an agent webhook instead.

​
Agent Usage Feed

GET /api/v1/agents/metrics/usage returns every agent in your organization, newest first, with its creator, its consumers, who it is shared with, and its token usage over a date range. Use it to feed agent data into a BI tool or data warehouse; Pull Agent Usage into Your Warehouse has copy-paste recipes. The caller needs both the View company metrics and Export usage data permissions. Admins, Security Admins, and Analytics Admins have both. Use a personal API key from a user who holds them.
The response has count (total agents), next_cursor, and data. Each item in data carries:
  • id, name, description, is_disabled, created_at
  • creator: id, email, full_name of the agent’s current owner. That’s the user who created it, unless ownership was transferred (for example when the creator was offboarded)
  • usage: run_count, cost_usd, and token counts over the range, counting every run, including eval and test runs (they spend tokens too). input_tokens is uncached prompt tokens; cache_read_tokens and cache_creation_tokens are counted separately; reasoning_tokens is 0 where the model bills reasoning inside output_tokens. The buckets don’t overlap, and total_tokens is their sum
  • consumer_count: how many users started a run of the agent in the range
  • consumers: the top consumer_limit of those users by run count, each with the same usage breakdown for their own runs. Automated runs (schedules, webhooks, triggers) count toward the user each run is attributed to on the agent’s Runs tab
  • share_scope: private (owner only), specific (shared with chosen users or groups), or organization (everyone in the org). An agent made visible to the whole workspace reads organization even without an organization entry in shared_with
  • shared_with_count and shared_with: who can use the agent, one entry per grant, listing up to 50 (shared_with_count is the full total; page every grant with GET /api/v1/agents/{agent_id}/shares). Grants to deleted users, groups, or teams are left out of both fields and of share_scope. Each has principal_type (user, group, role, team, or organization), principal_id, name, email (users only), and permission (can_use or can_edit). Groups and teams are listed as one entry, not expanded to their members
consumers is who actually used the agent in the range. shared_with is who has access, whether they used it or not. Agents with no runs in the range are still listed, with zero usage. What the feed leaves out, so you can reconcile it:
  • Deleted agents and Runlayer’s built-in agents (Runlayer Assistant, Researcher) aren’t listed, even for runs inside the range, so totals won’t match billing.
  • Deleting an agent removes its history from the feed. With the cookbook’s “replace the last two days” sync, a deleted agent’s last two days of usage also disappear from your warehouse.
  • name, creator, share_scope, and shared_with are current state at pull time, not as of the date range. Only usage and consumers are scoped to the range.
Usage comes from each agent run’s own accounting, the same numbers as an agent’s cost card and Monitor tab. The Enterprise AI Usage tab on the Usage page counts session-level spend across all AI clients, so its totals won’t match this feed. Runs still in progress report their tokens once they finish, so the most recent day can still change. When loading into a warehouse, re-pull the last two days on each sync instead of only appending new ones.

​
All consumers of one agent

When consumer_count is larger than consumers, page the full list with GET /api/v1/agents/{agent_id}/metrics/consumers. It takes the same start_date, end_date, and cursor parameters, plus limit (1–500, default 100), and returns next_cursor and data (each entry has user and usage).

​
Large ranges

Both endpoints sum individual runs and return 422 rather than a slow or partial answer when there are more than 100,000 in the range:
  • Agent usage feed: counts the runs of every agent on the page. Narrow the date range or lower limit and retry.
  • Consumers of one agent: counts that agent’s runs only, so limit doesn’t help. Narrow the date range.

​
Search agents, skills and connectors

Use these endpoints to build your own catalog or “discover first” page, so people find an existing agent, skill or connector before building a new one. Each one returns only what the caller can access. Call them with a personal API key or a user token, so results match the person searching.
  • query matches the name or description. For agents, every word must match in any order, so release notes also finds “Notes for each release”.
  • Agents: filter=org_wide lists only agents shared with the whole workspace. sort_by takes created_at, name, last_used_at, run_count or user_count (distinct people who ran it). Each agent includes description, created_by_name, run_count, user_count, last_used_at and its connector and skill counts.
  • Page with skip and limit (up to 100 per page; 500 for connectors). Each response has data and count.
The same searches are available to AI clients as the Runlayer MCP tools list_agents, list_skills and list_servers. See Find an existing agent before you build.

​
Artifacts and public links

List artifacts, read their content, and turn public links off from your own tools, for example to feed a DLP scanner. Use a personal API key. Results follow the key owner’s access: a user with Manage Agents can reach every artifact in the workspace.
  • filter takes created_by_me (default), shared_with_me, all, editable_by_me or full_access_by_me. With Manage Agents, full_access_by_me returns every artifact in the workspace, including ones nobody shared with the caller.
  • Each artifact includes is_public and public_requires_email. Callers with full access also get public_url, public_expires_at and public_opens_left. A link counts as public only while it’s live: it ends 30 days after it was turned on or after 5 opens. See Public links.
  • Page with skip and limit (up to 100 per page). The response has data and count.
  • With full access to the artifact, you can always turn its link off. Turning one on through the API needs the same organization setting as the app.
  • There is no webhook before a link goes public. To react when one is turned on, watch the audit log for agent_artifact_public_access_changed (with is_public and requires_email), through SIEM Export or the Runlayer MCP export_audit_logs tool. Admins can also turn public links off for the whole workspace in Settings → Artifacts.

​
API Keys

Create API keys in Settings → Personal API keys or Settings → Organization API keys. (For a map of all admin settings pages, see Where to Find Key Settings.)
  • Personal API keys authenticate as the user who created them and work for user-scoped management API calls.
  • Organization API keys authenticate as the workspace and are scoped by role. Use them for workload-specific automation that should not depend on a user’s session.
  • Agent account API keys authenticate as an agent account on the MCP gateway only, not on the management API. Create them from the agent account page (⋯ → Manage API keys). See Using an API key.
Organization API key roles include:
For deploy pipelines, see CI/CD with organization API keys.

Analytics

View usage metrics

Audit Logs

Activity history