Sourcebee — beta

Agent API Access

MCP Server

Sourcebee runs a Model Context Protocol server, so your agent can work with your org's pull requests, CI/CD, deploys, and insights directly. It answers from Sourcebee's synced copy of your GitHub data, so calls are fast and don't use your GitHub API quota.

36 tools and 13 ready-made prompts. Agent access is included with every seat.

Connect

  1. 1. Create an agent API key

    In Sourcebee, open Account → Agent API Keys and create a key. You can give it an expiry date. The secret is shown once, so copy it before you close the dialog. After you create the key, the app shows the setup for your client with the key already filled in.

  2. 2. Add the server to your client

    Transport is streamable HTTP with a Bearer token. Replace YOUR_AGENT_API_KEY with your key.

    Terminal

    claude mcp add --transport http sourcebee https://api.sourcebee.co/mcp \
  --header "Authorization: Bearer YOUR_AGENT_API_KEY"

Access and limits

  • A key acts as you. It reaches only the orgs you're a member of, and every call is checked against your current membership.
  • Keys have no scopes. A key can call the 7 tools that change settings as well as the read-only ones. The server tells agents to confirm a change with you before they make it.
  • Revoke a key at any time from the same page. A revoked key stops working at once.
  • Each user can make up to 300 calls a minute. The limit only stops runaway loops.

Prompts (13)

Ready-made questions your client can run in one step. In Claude Code they appear as slash commands, for example /mcp__sourcebee__review-queue. Other clients list them in their prompt or attachment menu.

org (optional)
Org name or ID to scope to
team (optional)
Team name or ID to scope to
repo (optional)
Repository name or ID to scope to
range (optional)
Time range such as 'last 7 days' or 'last 30 days'
since (optional)
How far back to look, as a duration such as 15m, 2h or 1d, or an RFC 3339 time; 10m if none is given
cadence (optional)
daily, weekly, monthly or quarterly (default weekly)
How every prompt formats its answer

Lead with a one-sentence answer. Where the result compares several items on the same attributes, present it as a markdown table with one row per item and the columns above, keeping cells short and any long text such as a title in the last column. If your interface cannot render a table, give one line per item with the same fields in the same order, separated by a vertical bar. Show at most 15 rows and say how many more there are. Otherwise use a short list. Write in plain words: do not quote field, parameter or tool names, and say "the week is not over yet" rather than naming a flag. Where a value is compared with a target or benchmark, put 🟢 before it when it is on the good side and 🔴 when it is on the bad side, and keep the words above or below next to the marker. Which side is good depends on the metric's direction: lower is better for durations, wait times and failure rates, higher is better for success rates. Use no marker when there is no target or benchmark, or when the metric has no better or worse direction (such as pull request count). If there are no results, say so in one line instead of showing an empty table.

Review queue

review-queue

“Which pull requests are waiting on my review?”

org team repo

Uses list_my_orgs, get_me, list_pull_requests, list_pr_reviews

Instructions sent to the agent

Find open pull requests waiting on my review. Call list_my_orgs, then get_me for my GitHub login, then list_pull_requests with state=open. For candidates call list_pr_reviews and keep PRs where I am a requested reviewer and have not reviewed. Order by priority, then age.

What you get back

A table with columns PR (repo and number), title, author, waiting since and priority, in the order given.

My PRs and blockers

my-prs-blocked

“Which of my open PRs are stuck, and on what?”

org team repo

Uses get_me, list_pull_requests, get_pull_request

Instructions sent to the agent

Show my open pull requests and what blocks each one. Call get_me for my GitHub login, then list_pull_requests with author set to it and state=open. For each PR use get_pull_request to read review status and the latest check suite. Say whether it waits on review, on failing CI, or on me.

What you get back

A table with columns PR (repo and number), title, blocked on (review, CI or you) and waiting since. Follow it with one line saying which to unblock first.

Stale reviews

stale-reviews

“Which PRs have been waiting on a review for days?”

org team repo range

Uses list_pull_requests, list_pr_reviews

Instructions sent to the agent

Find open pull requests whose review requests have sat idle. Call list_pull_requests with state=open and sort=gh_updated_at, order=asc. Use list_pr_reviews to confirm no review activity. Report each PR with its reviewer, how long it has waited, and the repo.

What you get back

A table with columns PR (repo and number), title, reviewer and waiting time, longest wait first.

Priority queue

priority-queue

“What are the urgent and high-priority PRs right now?”

org team repo

Uses get_priority_limits, list_pull_requests

Instructions sent to the agent

Show the review priority queue. Call get_priority_limits, then list_pull_requests with state=open and sort=priority. Group by urgent, high and normal. Note how many slots each level has left.

What you get back

One small table per priority level with columns PR (repo and number), title and age, each under a line giving the slots left at that level.

Where PRs get stuck

where-prs-get-stuck

“Where do our pull requests spend the most time?”

org team repo range

Uses list_insights_metrics, query_insights, get_industry_benchmarks

Instructions sent to the agent

Find where pull requests get stuck. Call list_insights_metrics to pick the PR flow metrics (time to first review, review time, cycle time or similar), then query_insights for each over the range. Name the slowest stage and compare it with get_industry_benchmarks.

What you get back

A table with columns stage, median time and the benchmark range, slowest first. Follow it with one sentence naming the slowest stage.

Flakiest checks

flakiest-checks

“Which CI checks are flaky?”

org team repo range

Uses list_insights_metrics, query_insights, list_check_run_history

Instructions sent to the agent

Find the flakiest CI checks. Call list_insights_metrics for the flakiness and failure-by-check metrics, then query_insights grouped by check_name over the range. Rank the checks. Use list_check_run_history on the top ones to confirm.

What you get back

A table with columns check, repo, flake rate and runs, most flaky first.

CI trend

ci-trend

“Is our CI getting better or worse?”

org team repo range

Uses list_insights_metrics, query_insights

Instructions sent to the agent

Show how CI health is trending. Call list_insights_metrics for the CI health metrics, then query_insights grouped by week over the range. Say whether failure rate, duration and wasted minutes are improving or getting worse.

What you get back

A table with one row per week and columns failure rate, median duration and wasted minutes. Follow it with one sentence on the direction.

Failing now

failing-now

“What is failing on our default branches right now?”

org team repo

Uses list_cicd

Instructions sent to the agent

Show what is failing in CI right now. Call list_cicd with status=["failure"] and tracked_reason=["default_branch"]. Group by repo. For each failure give the ref, the failing check runs, the actor and how long ago it ran.

What you get back

A table with columns repo, ref, failing checks, actor and how long ago. If nothing is failing, say so in one line.

Cycle time vs benchmark

cycle-time-vs-benchmark

“How does our cycle time compare with the industry?”

org team repo range

Uses query_insights, get_industry_benchmarks

Instructions sent to the agent

Compare my cycle time with industry benchmarks. Call query_insights for the cycle time metric over the range, and get_industry_benchmarks with the metric filter. Say whether I am inside the low-high range. If there is no range, say so.

What you get back

A table with columns metric, yours, benchmark range and verdict, then one sentence on what it means.

What shipped

what-shipped

“What did we ship last week?”

org team repo range

Uses list_pull_requests

Instructions sent to the agent

List what shipped. Call list_pull_requests with state=merged, sort=gh_updated_at, over the range. Group by repo and give one line per PR with its number, title and author.

What you get back

A short list per repo, one line per PR. A table is not needed here.

Pull request changes

pr-changes

“What changed on our pull requests since I last looked?”

since org team repo

Uses list_my_orgs, list_pull_requests

Instructions sent to the agent

Report pull request changes since the time given below. Call list_my_orgs, then list_pull_requests with state=all and updated_since set to that time minus five minutes, because a row is stamped when its transaction starts and can become visible later. Drop any PR you have already reported. This covers the pull request itself; a new review or CI run does not move it. If nothing changed, say so in one line with the time of this check, so a repeat run stays cheap.

What you get back

A table with columns PR (repo and number), title, what happened (opened, merged, closed or updated) and when, newest first, then the time of this check.

CI changes

ci-changes

“Did any CI results change since I last looked?”

since org team repo

Uses list_my_orgs, list_cicd

Instructions sent to the agent

Report CI results that changed since the time given below. Call list_my_orgs, then list_cicd with updated_since set to that time minus five minutes, because a row is stamped when its transaction starts and can become visible later. Drop any ref you have already reported at the same status. List new failures first. If nothing changed, say so in one line with the time of this check, so a repeat run stays cheap.

What you get back

A table with columns repo, ref, status now, failing checks and when, failures first, then the time of this check.

Period summary

period-summary

“Write up last quarter for the leadership team.”

cadence org team repo

Uses get_periodic_report

Instructions sent to the agent

Write an engineering summary for the cadence given below (daily, weekly, monthly or quarterly; weekly if none is given; reject any other value). Call get_periodic_report with that cadence; each metric carries its direction and, where the org set one, its target. If the period is not complete, say it is still in progress and the numbers are partial. For daily and weekly, cover throughput, review speed and CI health, then list the open PRs that need attention. For monthly and quarterly, lead with three to five headline takeaways, compare each metric with the prior period in the report, and explain trends rather than listing activity.

What you get back

For daily and weekly, a table with columns metric, this period, prior period and target, then a short list of what needs attention. For monthly and quarterly, the headline takeaways first, then the same table.

How agents use it

The server sends these instructions to your client when it connects. They're useful for you to know too.

Sourcebee reads a synced mirror of an org's GitHub pull requests and CI/CD.

  • Call list_my_orgs first to get org_id. Call get_me to learn the caller's GitHub login for "my" questions.
  • Identifiers differ between tools. list_pull_requests returns both id and number. list_pr_reviews and update_pr_settings take the PR's id (pr_id). get_pull_request takes pr_id, or repo_id plus number.
  • Fields prefixed gh_ come from GitHub and are read-only. Fields prefixed sb_ are Sourcebee settings.
  • Tools named update_* change real data. Confirm the exact change with the user before calling one.
  • get_org_narration is a cached snapshot and can differ from live query_insights values. Prefer live queries for numbers.
  • Call list_insights_metrics before query_insights to see valid group_by and agg combinations.
  • A metric whose group_bys include origin can be split by who made the PR: ai, automation (bots such as dependabot) or unclassified. unclassified is not human work: it is everyone the AI patterns did not match. Treat ai figures as a lower bound, and ignore any bucket with a small count.

Tools (36)

Generated from sourcebee-mcp v0.1.0. Descriptions and parameters are the exact text the server reports to clients.

Jump to a tool

Start here (2)

list_my_orgs

read-only

List the Sourcebee orgs the authenticated user is a member of

get_me

read-only

Get the caller's own identity in a Sourcebee org: github_user_id, github_login, name, role, is_owner, and team_ids. Use it to resolve "my" in questions like "which PRs are waiting on my review"

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

Pull requests (6)

get_priority_limits

read-only

Get a Sourcebee org's caps on high (1) and urgent (2) open pull requests, plus current usage. Two caps apply together, each level counted separately: priority_cap_org (whole org) and priority_cap_repo (per repo, same number for every repo). A stored null means the default and 0 means unlimited; effective_* are the values actually enforced. usage has the org's current counts and each repo with flagged PRs. Check this before update_pr_settings to see whether a level has a free slot

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

get_pull_request

read-only

Get a single pull request with repo, priority, teams, reviews, requested reviewers, labels and latest check suite

Parameter Type Required Description
number integer no Pull request number - required with repo_id unless pr_id is given
org_id integer yes Sourcebee org ID
pr_id integer no Sourcebee pull request ID (the id field from list_pull_requests) - alternative to repo_id plus number
repo_id integer no Repo ID the PR belongs to - required with number unless pr_id is given

list_pr_labels

read-only

List all labels attached to a pull request

Parameter Type Required Description
org_id integer yes Sourcebee org ID
pr_id integer yes Sourcebee pull request ID (the id field from list_pull_requests)

list_pr_reviews

read-only

List all reviews for a pull request, newest first

Parameter Type Required Description
created_since string no RFC 3339 timestamp. Only rows Sourcebee first recorded at or after this time (not GitHub's creation time). For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id
org_id integer yes Sourcebee org ID
pr_id integer yes Sourcebee pull request ID (the id field from list_pull_requests)
updated_since string no RFC 3339 timestamp. Only rows that changed at or after this time. For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id. A review changing state (commented to approved, or dismissed) counts

list_pull_requests

read-only

List pull requests for a Sourcebee org

Parameter Type Required Description
author array | null no Filter to PRs authored by any of these GitHub logins
created_since string no RFC 3339 timestamp. Only rows Sourcebee first recorded at or after this time (not GitHub's creation time). For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id
label array | null no Filter to PRs carrying any of these label names
limit integer no Max results to return, 1-100 (default 25)
order string no Sort order: desc (default) or asc
org_id integer yes Sourcebee org ID to query
priority integer | null no Filter by Sourcebee priority (0-2)
repo_id array | null no Filter to PRs in any of these repo IDs
sort string no Sort field: gh_updated_at (default), opened_at, number, priority, repo_name, author_login, review_status, cicd_status, team_name, or label. All respect order except priority (always urgent-first). review_status/cicd_status/team_name/label rank by rollup or alphabetically-first value; PRs with no check suite / no team / no label sort last.
start integer no Offset for pagination (default 0)
state string no Filter by state: open (default), closed, merged, or all. When polling with created_since or updated_since, use all, or a PR opened and merged between two checks is missed
team_id integer | null no Filter to PRs whose repo belongs to this team
updated_since string no RFC 3339 timestamp. Only rows that changed at or after this time. For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id. Covers the PR row only; new reviews and CI runs do not count, poll list_pr_reviews and list_cicd for those

update_pr_settings

writes data

Set a pull request's review priority (0 normal, 1 high, 2 urgent). Records the caller as who set it. Fails with a cap-reached error when the org or the PR's repo has no free slots at that level (see get_priority_limits)

Parameter Type Required Description
org_id integer yes Sourcebee org ID
pr_id integer yes Sourcebee pull request ID (the id field from list_pull_requests)
priority integer yes Review priority: 0 (normal), 1 (high), or 2 (urgent)

CI/CD & deploys (9)

get_cicd_depth

read-only

Get a Sourcebee org's CI/CD health-view depth caps: cicd_depth (max runs shown per branch) and cicd_ref_depth (max tags/releases/pre-releases shown per repo, each type counted separately)

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

get_cicd_ref_scoping

read-only

Get a Sourcebee org's CI/CD branch/tag/release tracking config — which branches/tags/releases list_cicd includes and why

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

get_deploy_pull_requests

read-only

Get the pull requests that shipped in a specific deploy/release

Parameter Type Required Description
deploy_id integer yes Deploy ID to list shipped PRs for
org_id integer yes Sourcebee org ID

list_check_run_history

read-only

Batched per-check run history (flake signature) for one or more named checks on a repo, oldest run first per check — one call for a whole table's worth of checks instead of one request each. Each check also gets a workflow_url (its stable GitHub Actions workflow-file page) backfilled from org sync and kept live via the workflow_run webhook; nil if neither has supplied it yet, or the check isn't a GitHub Actions check. Each run carries status/gh_created_at/url plus commit_sha and actor (from the run's check suite, same fields as list_cicd's items) and duration_mins (this run's own duration, nil if it never completed)

Parameter Type Required Description
check_name array | null yes One or more exact check-run names to fetch history for (e.g. "test (node 20)") — not a search/prefix match. Max 50 values.
limit integer no Max runs returned per check, 1-50 (default 12) — applies independently to each requested check, not as a shared budget
org_id integer yes Sourcebee org ID
repo_id integer yes Sourcebee repo ID (the id field from list_repositories/list_cicd)

list_cicd

read-only

List CI/CD check suite runs for a Sourcebee org, one row per ref by default (its current status). Each row's tracked_reason explains why it's in scope: default_branch, protected_branch, branch_pattern, tag, release, or pre-release. Pass group_by=repo or group_by=ref for a nested response (repos, optionally sub-grouped by ref) instead of the flat list

Parameter Type Required Description
actor array | null no Filter to runs triggered by any of these GitHub logins
created_since string no RFC 3339 timestamp. Only rows Sourcebee first recorded at or after this time (not GitHub's creation time). For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id. Applied after depth windowing, like status
depth integer no Max eligible runs per branch before sort/pagination, 1-100 (default: org's configured depth, usually 2)
group_by string no repo (nest runs under their repo) or ref (nest under repo, then under ref within it). Omit for the flat one-row-per-run shape. Changes the response from {total, items} to {total, groups}, see docs/032-cicd-group-by.md for the nested shape.
limit integer no Max results to return, 1-100 (default 25). With group_by set, this caps repos returned, not nested items/refs.
order string no Sort order: asc or desc. Defaults to asc (worst-first) when sort=status, desc for every other sort field. With group_by=ref and no explicit sort, also flips the default newest-first ref ordering to oldest-first.
org_id integer yes Sourcebee org ID to query
ref_depth integer | null no Max tags/releases/pre-releases per repo, each type counted separately, 1-100. Does not apply to branches. Default: the org's configured ref depth, usually 2. Pass 0 to force uncapped for this call.
repo_id array | null no Filter to these repo IDs
sort string no Sort field: status (default, severity order: failure/pending/cancelled/success), gh_created_at, gh_updated_at, repo_name, actor_login, team_name, or ref_recency. team_name ranks by the alphabetically-first team among the entry's teams; entries with no teams sort last in both directions. ref_recency ranks by each row's own ref recency (a tag/release's own GitHub timestamp, else its most recent run's) — at the default depth=1 this is one row per ref, so with type/status filters and start/limit it's the org-wide, paginated-over-refs view (e.g. latest successful releases) with no group_by needed. actor_login and ref_recency are rejected when group_by is set — not meaningful for a whole repo/ref bucket, and group_by=ref already orders refs by that same recency unconditionally. With group_by=ref, sort only affects which repo appears first; refs within a repo are always newest-first regardless of sort.
start integer no Offset for pagination (default 0). With group_by set, paginates over repos (the outer group), never over the nested items/refs.
status array | null no Filter by status: success, pending, failure, cancelled
team_id array | null no Filter to repos belonging to any of these teams
tracked_reason array | null no Filter by why the ref is tracked: default_branch, protected_branch, branch_pattern, tag, release, pre-release. Applied after depth windowing, like status
type array | null no Filter by ref type: branch, tag, release, pre-release
updated_since string no RFC 3339 timestamp. Only rows that changed at or after this time. For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id. Applied after depth windowing, like status. A run moving from pending to failure counts as an update

list_deploys

read-only

List deploy/release events for a repo (branch-based deploys or GitHub Releases), newest first

Parameter Type Required Description
created_since string no RFC 3339 timestamp. Only rows Sourcebee first recorded at or after this time (not GitHub's creation time). For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id. Deploys are never updated, so there is no updated_since
limit integer no Max results to return, 1-100 (default 25)
org_id integer yes Sourcebee org ID to query
repo_id integer yes Repo ID to list deploys for
start integer no Offset for pagination (default 0)

list_pr_deploys

read-only

List the deploys/releases a pull request shipped in, oldest first — answers 'when did this PR ship'

Parameter Type Required Description
created_since string no RFC 3339 timestamp. Only rows Sourcebee first recorded at or after this time (not GitHub's creation time). For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id. Deploys are never updated, so there is no updated_since
org_id integer yes Sourcebee org ID
pr_id integer yes Pull request ID

update_cicd_depth

writes data

Set a Sourcebee org's CI/CD health-view depth caps. Owner only. Partial patch — pass only the field(s) you want to change; an omitted field is left unchanged. Neither field can be set to null/uncapped through this tool

Parameter Type Required Description
cicd_depth integer | null no Max eligible runs per branch, 1-100. Omit to leave unchanged.
cicd_ref_depth integer | null no Max tags/releases/pre-releases per repo, each type counted separately, 1-100. Omit to leave unchanged. There is no way to clear this back to uncapped through this tool.
org_id integer yes Sourcebee org ID

update_cicd_ref_scoping

replaces config

Set a Sourcebee org's CI/CD branch/tag/release tracking config. Admin/owner only. Replaces the full config, not a partial patch — pass every field

Parameter Type Required Description
branch_patterns array | null yes Name patterns to track regardless of protection status. Single '*' wildcard, leading/trailing/embedded (e.g. release/*, *-hotfix) - same syntax as GitHub's own branch-protection pattern field, not regex
org_id integer yes Sourcebee org ID
tag_patterns array | null yes Name-filter patterns for tags/releases/pre-releases, same wildcard syntax as branch_patterns. Empty means no filter - every type enabled by the three toggles above is tracked
track_default_branch boolean yes Track the repo's current GitHub default branch (self-healing, always reflects the live default branch)
track_prereleases boolean yes Track prerelease GitHub releases
track_protected_branches boolean yes Track branches matching a GitHub branch-protection pattern (self-healing, synced from GitHub's live protected-branches list)
track_releases boolean yes Track published, non-prerelease GitHub releases
track_tags boolean yes Track plain tags (no associated GitHub release)

Insights & reports (8)

get_industry_benchmarks

read-only

List confirmed industry benchmark ranges (low/high plus citation) for insights metrics — global, not org-specific. Only metrics with an admin-confirmed benchmark are returned

Parameter Type Required Description
metric string no Return only this metric slug (see list_insights_metrics)
only_with_range boolean no Return only benchmarks that have both a low and a high value, dropping the citation-only entries
org_id integer yes Sourcebee org ID to query

get_insights_targets

read-only

Get the org's saved insights targets (cycle time, review wait, etc.) — user-set, static-benchmark, or AI-suggested values

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

get_org_interpretation

read-only

Get a per-chart AI interpretation for a metric, if one has been cached — serve-only, never calls Anthropic (no MCP path to trigger a new one; use the sourcebee-app UI for that). Returns disabled:true if AI is off, or an empty result on a cache miss. A result has headline (one plain-text sentence) and details (supporting facts, each may use inline **bold**); range is the window covered and cached_at when it was generated; text is the same content as one markdown string, deprecated in favour of headline and details

Parameter Type Required Description
chart_id string yes A metric slug from the insights metric catalog (same enum query_insights accepts)
org_id integer yes Sourcebee org ID to query
range string no 7d, 30d (default), or 90d

get_org_narration

read-only

Get the org-overview AI narration, if one has been generated — serve-only, never calls Anthropic. Returns disabled:true if AI is off, or an empty result if nothing's been generated for this org yet. A result has headline (one plain-text sentence) and details (2-5 supporting facts, each may use inline **bold**); range is the fixed window covered (always 30d) and cached_at when it was generated; text is the same content as one markdown string, deprecated in favour of headline and details

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

get_periodic_report

read-only

Build a daily/weekly/monthly/quarterly (or custom from/to) periodic report for a Sourcebee org, optionally scoped to teams and/or repos (repo_id and team_id intersect when both are passed) — defaults to the org's dashboard layout's report-flagged metrics (falling back to pr_flow+ci_health if none), or pass metrics to override. Each metric includes its value for the period, the prior period's value for comparison, count and prior_count (the rows behind each value; treat a change computed from a small count as noise), a series (daily unless bucket=week, calendar-filled like query_insights: null where a bucket has no data), a suggested_chart hint (line/bar/stat_tile), and an optional flag callout. PR metrics (not CI metrics) also carry an ai object: the same value, prior_value and series restricted to AI PRs (query_insights origin=ai; see get_ai_detection), plus count and prior_count, the AI PRs behind each value. Treat a small count as noise. With no AI PRs the ai value is 0 for pr_count and null for every other metric, because a duration or rate over no PRs is unknown, not zero. With narration=true the report also carries narrative_headline (one sentence) and narrative_details (supporting facts, each may use inline **bold**); narrative is the same content as one markdown string

Parameter Type Required Description
bucket string no day (default) or week - the size of each series point. series (and ai.series) match query_insights for the same metric and group_by, calendar-filled: a bucket with no data has value null, or 0 for pr_count. value and prior_value ignore the bucket and the fill. Weeks start on Monday and are keyed by that date; the first can be partial when the period starts mid-week and the last is the week in progress
cadence string no daily, weekly, monthly, or quarterly - required unless from/to are both set; ignored (but still echoed) when from/to are set
fill boolean | null no Default true: series and ai.series include every bucket in the period, with value null (or 0 for pr_count) where there is no data. false leaves empty buckets out. value, prior_value and the ai figures are the same either way
from string no Custom period start, ISO 8601 date - requires to, overrides cadence
metrics array | null no Explicit metric slugs to override the org's layout-derived default (falls back to pr_flow+ci_health if the layout yields nothing) - call list_insights_metrics for the full enum
narration boolean no Also generate/return period-aware AI narration for this exact report (narrative_headline, narrative_details and narrative) - a real Anthropic call on a cache miss, so off by default
org_id integer yes Sourcebee org ID to report on
repo_id array | null no Scope the report to any of these repos instead of the whole org - combined with team_id it intersects (repos that are in the list AND owned by one of the teams)
team_id array | null no Scope the report to any of these teams' owned repos instead of the whole org
to string no Custom period end, ISO 8601 date, inclusive - requires from, overrides cadence

list_insights_metrics

read-only

List the full insights metric catalog — every metric's title, description, category, unit, and which group_bys/aggs are valid for it

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

query_insights

read-only

Query a single insights metric for a Sourcebee org. Call list_insights_metrics first for the full metric enum and valid group_by/agg options per metric. group_by day and week return every calendar bucket in the range; a bucket with no data has value null (not 0, which would read as instant or never failing), except pr_count and ci_wasted_mins_by_check where an empty bucket is a real 0. Ignore null buckets when averaging

Parameter Type Required Description
agg string no avg (default), p50, or p90 - percentiles only apply to distribution-backed metrics (cycle_time_hrs, review_wait_hrs, pr_size_lines, ci_duration_mins, reviews_per_pr, approval_to_merge_hrs, review_request_to_first_review_hrs, draft_duration_hrs, ci_runs_per_pr, rework_lines, time_to_green_hrs, ci_duration_by_check_mins)
fill boolean | null no Default true: group_by day or week returns every calendar bucket in the range, with value null (or 0 for pr_count and ci_wasted_mins_by_check) where nothing qualified. false returns only the buckets that have data. No effect on other group_by values or on split
from string no Custom range start, ISO 8601 date (e.g. 2026-01-01) - requires to, mutually exclusive with range
group_by string yes day, week, repo, or team - plus check_name, valid only for ci_flakiness_rate, ci_failure_rate_by_check, ci_duration_by_check_mins, and ci_wasted_mins_by_check - plus origin or agent, valid only for PR metrics (origin: see origin; agent: one bucket per AI agent named in get_ai_detection, plus multiple when a PR matches more than one agent, covering AI PRs only and not combinable with origin or split)
limit integer no Max series points returned. Default is unbounded (every matching bucket). Same group_by-dimension-only restriction as sort
metric string yes cycle_time_hrs, review_wait_hrs, pr_count, pr_size_lines, ci_duration_mins, ci_success_rate, merged_pr_rate, self_merge_rate, reviews_per_pr, approval_to_merge_hrs, review_request_to_first_review_hrs, draft_duration_hrs, stale_review_request_rate, ci_runs_per_pr, force_push_rate, rework_lines, ci_flakiness_rate, time_to_green_hrs, ci_failure_rate_by_check, ci_duration_by_check_mins, or ci_wasted_mins_by_check
order string no asc or desc, default desc. Same group_by-dimension-only restriction as sort
org_id integer yes Sourcebee org ID to query
origin string no ai, automation, or unclassified - restrict a PR metric to PRs of that origin. ai means the PR's author login, head branch or a label matches an AI agent's patterns (get_ai_detection); automation means a bot author that is not AI (dependabot, renovate); unclassified is everyone else, people and any AI the patterns missed, so it is NOT a measure of human work. Every point then carries count, the PRs behind the value; treat a small count as noise. Not valid with split, group_by=origin or group_by=agent, and not valid for CI metrics
range string no 7d, 30d, or 90d - mutually exclusive with from/to; exactly one of range or from+to is required
repo_id array | null no Filter to any of these repo IDs
sort string no value, count, or bucket - only valid when group_by is repo, team, check_name, origin or agent (400s combined with day/week, whose time order pagination would otherwise break). sort=count is valid for ci_failure_rate_by_check and ci_flakiness_rate (the CI metrics with a count denominator) and for PR metrics (the PRs behind each value) when origin, split or group_by=origin|agent is set. Omit for the default order (bucket ascending for day/week, value descending for dimension group_bys)
split string no origin - return one series per origin in a single response, each point tagged with origin and count. Works with any group_by except origin; with repo or team, sort may only be bucket or count and start/limit page over buckets. PR metrics only
start integer no Pagination offset into the sorted series (default 0). Same group_by-dimension-only restriction as sort
team_id array | null no Filter to repos owned by any of these teams
to string no Custom range end, ISO 8601 date, inclusive - requires from, mutually exclusive with range

get_target_suggestion

calls AI

Get (or generate, on a cache miss) an AI-suggested target value for a metric, grounded in the org's own trailing p50/p90 plus the live industry benchmark. The metric must already have a saved target

Parameter Type Required Description
metric string yes A metric slug from the insights metric catalog that has a saved target
org_id integer yes Sourcebee org ID to query

Org, teams & repos (4)

get_team

read-only

Get a team's membership and repos

Parameter Type Required Description
org_id integer yes Sourcebee org ID
team_id integer yes Team ID to fetch

list_actors

read-only

Search the distinct GitHub identities (human or bot) seen anywhere in a Sourcebee org's synced data — PR authors, CI/CD actors, reviewers. Superset of org members since bots aren't org members.

Parameter Type Required Description
limit integer no Max results to return, 1-200 (default 100)
org_id integer yes Sourcebee org ID to query
q string no Search login (case-insensitive substring match)
source array | null no Restrict to one or more of: pr_author, cicd_actor, reviewer. Omit for the unfiltered union of all three — a PR author and a CI actor aren't the same population.
start integer no Offset for pagination (default 0)

list_org_members

read-only

List members of a Sourcebee org

Parameter Type Required Description
created_since string no RFC 3339 timestamp. Only rows Sourcebee first recorded at or after this time (not GitHub's creation time). For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id
limit integer no Max results to return, 1-100 (default 100)
order string no Sort order: asc (default) or desc
org_id integer yes Sourcebee org ID to query
q string no Search across github_login, name, and location
sort string no Sort field: github_login (default), name, or gh_updated_at
start integer no Offset for pagination (default 0)
team_id array | null no Filter to members of any of these team IDs
timezone array | null no Filter to members with any of these timezones (exact match)
updated_since string no RFC 3339 timestamp. Only rows that changed at or after this time. For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id. Covers the GitHub membership row only, not a member's Sourcebee settings

list_repositories

read-only

List repositories in a Sourcebee org

Parameter Type Required Description
created_since string no RFC 3339 timestamp. Only rows Sourcebee first recorded at or after this time (not GitHub's creation time). For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id
include_archived boolean no Include archived repositories (default false)
limit integer no Max results to return, 1-200 (default 100)
order string no Sort order: asc (default) or desc
org_id integer yes Sourcebee org ID to query
q string no Search across name, full_name, and description
sort string no Sort field: name (default), full_name, or gh_updated_at
start integer no Offset for pagination (default 0)
updated_since string no RFC 3339 timestamp. Only rows that changed at or after this time. For polling, pass the time of your last check minus a few minutes of overlap, and dedupe by id

Bookmarks (6)

get_my_bookmarks

read-only

Get the caller's own personal bookmark layout (saved links) for the org, or an empty layout if nothing's been saved yet. Private — only ever the caller's own

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

get_org_bookmarks

read-only

Get the org-wide bookmark layout (saved links), or an empty layout if nothing's been saved yet

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

get_team_bookmarks

read-only

Get one team's bookmark layout (saved links), or an empty layout if nothing's been saved yet. Any org member may view any team's layout

Parameter Type Required Description
org_id integer yes Sourcebee org ID
team_id integer yes Team ID

update_my_bookmarks

replaces config

Replace the caller's own personal bookmark layout for the org

Parameter Type Required Description
bookmarks object yes Full BookmarkData object, replacing the current one entirely (not merged, no partial patch).
Full schema for bookmarks 
{
  "description": "Full BookmarkData object, replacing the current one entirely (not merged, no partial patch).",
  "properties": {
    "columnCount": {
      "description": "1-4; layout column count, independent of section positions",
      "type": [
        "null",
        "integer"
      ]
    },
    "sections": {
      "items": {
        "properties": {
          "column": {
            "description": "0-indexed target column; falls back to array position among sections if absent",
            "type": [
              "null",
              "integer"
            ]
          },
          "links": {
            "items": {
              "properties": {
                "description": {
                  "description": "Optional description shown under the link",
                  "type": [
                    "null",
                    "string"
                  ]
                },
                "faviconChip": {
                  "description": "Only meaningful when icon is '__favicon__'. Defaults to true if absent.",
                  "type": [
                    "null",
                    "boolean"
                  ]
                },
                "icon": {
                  "description": "Opaque to the backend, never validated. Unset/empty: client renders a generic default icon. '__favicon__': client renders the link's own site favicon (see faviconChip). '__none__': client renders no icon. Any other string: an icon-set key (Hugeicons/Simple Icons) the client resolves — the icon-set's contents change over time, so this is not an enum.",
                  "type": [
                    "null",
                    "string"
                  ]
                },
                "name": {
                  "description": "Display name for the link",
                  "type": "string"
                },
                "url": {
                  "description": "Target URL",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "url"
              ],
              "type": "object"
            },
            "type": [
              "null",
              "array"
            ]
          },
          "name": {
            "description": "Section title",
            "type": "string"
          }
        },
        "required": [
          "name",
          "links"
        ],
        "type": "object"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "selectedTeamId": {
      "description": "Personal bookmarks only: the team whose bookmarks the Teams tab shows by default for this member. Meaningless on org-wide or per-team bookmark data.",
      "type": [
        "null",
        "integer"
      ]
    }
  },
  "required": [
    "sections"
  ],
  "type": "object"
}
org_id integer yes Sourcebee org ID

update_org_bookmarks

replaces config

Replace the org-wide bookmark layout. Admin/owner only

Parameter Type Required Description
bookmarks object yes Full BookmarkData object, replacing the current one entirely (not merged, no partial patch).
Full schema for bookmarks 
{
  "description": "Full BookmarkData object, replacing the current one entirely (not merged, no partial patch).",
  "properties": {
    "columnCount": {
      "description": "1-4; layout column count, independent of section positions",
      "type": [
        "null",
        "integer"
      ]
    },
    "sections": {
      "items": {
        "properties": {
          "column": {
            "description": "0-indexed target column; falls back to array position among sections if absent",
            "type": [
              "null",
              "integer"
            ]
          },
          "links": {
            "items": {
              "properties": {
                "description": {
                  "description": "Optional description shown under the link",
                  "type": [
                    "null",
                    "string"
                  ]
                },
                "faviconChip": {
                  "description": "Only meaningful when icon is '__favicon__'. Defaults to true if absent.",
                  "type": [
                    "null",
                    "boolean"
                  ]
                },
                "icon": {
                  "description": "Opaque to the backend, never validated. Unset/empty: client renders a generic default icon. '__favicon__': client renders the link's own site favicon (see faviconChip). '__none__': client renders no icon. Any other string: an icon-set key (Hugeicons/Simple Icons) the client resolves — the icon-set's contents change over time, so this is not an enum.",
                  "type": [
                    "null",
                    "string"
                  ]
                },
                "name": {
                  "description": "Display name for the link",
                  "type": "string"
                },
                "url": {
                  "description": "Target URL",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "url"
              ],
              "type": "object"
            },
            "type": [
              "null",
              "array"
            ]
          },
          "name": {
            "description": "Section title",
            "type": "string"
          }
        },
        "required": [
          "name",
          "links"
        ],
        "type": "object"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "selectedTeamId": {
      "description": "Personal bookmarks only: the team whose bookmarks the Teams tab shows by default for this member. Meaningless on org-wide or per-team bookmark data.",
      "type": [
        "null",
        "integer"
      ]
    }
  },
  "required": [
    "sections"
  ],
  "type": "object"
}
org_id integer yes Sourcebee org ID

update_team_bookmarks

replaces config

Replace one team's bookmark layout. Restricted to members of that specific GitHub team

Parameter Type Required Description
bookmarks object yes Full BookmarkData object, replacing the current one entirely (not merged, no partial patch).
Full schema for bookmarks 
{
  "description": "Full BookmarkData object, replacing the current one entirely (not merged, no partial patch).",
  "properties": {
    "columnCount": {
      "description": "1-4; layout column count, independent of section positions",
      "type": [
        "null",
        "integer"
      ]
    },
    "sections": {
      "items": {
        "properties": {
          "column": {
            "description": "0-indexed target column; falls back to array position among sections if absent",
            "type": [
              "null",
              "integer"
            ]
          },
          "links": {
            "items": {
              "properties": {
                "description": {
                  "description": "Optional description shown under the link",
                  "type": [
                    "null",
                    "string"
                  ]
                },
                "faviconChip": {
                  "description": "Only meaningful when icon is '__favicon__'. Defaults to true if absent.",
                  "type": [
                    "null",
                    "boolean"
                  ]
                },
                "icon": {
                  "description": "Opaque to the backend, never validated. Unset/empty: client renders a generic default icon. '__favicon__': client renders the link's own site favicon (see faviconChip). '__none__': client renders no icon. Any other string: an icon-set key (Hugeicons/Simple Icons) the client resolves — the icon-set's contents change over time, so this is not an enum.",
                  "type": [
                    "null",
                    "string"
                  ]
                },
                "name": {
                  "description": "Display name for the link",
                  "type": "string"
                },
                "url": {
                  "description": "Target URL",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "url"
              ],
              "type": "object"
            },
            "type": [
              "null",
              "array"
            ]
          },
          "name": {
            "description": "Section title",
            "type": "string"
          }
        },
        "required": [
          "name",
          "links"
        ],
        "type": "object"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "selectedTeamId": {
      "description": "Personal bookmarks only: the team whose bookmarks the Teams tab shows by default for this member. Meaningless on org-wide or per-team bookmark data.",
      "type": [
        "null",
        "integer"
      ]
    }
  },
  "required": [
    "sections"
  ],
  "type": "object"
}
org_id integer yes Sourcebee org ID
team_id integer yes Team ID

Other (1)

get_ai_detection

read-only

Get the named AI agents (for example Claude or Copilot) whose patterns decide which pull requests count as AI for query_insights' origin filter, split and group_by, and which agent group_by=agent reports a PR under. Each agent has branch_patterns (head branch), author_patterns (PR author login) and label_patterns (label names), case-insensitive, '*' matches any run of characters. A PR is ai when any pattern of any agent matches. The stored agents are null where the org uses the shipped default; effective holds the agents actually used. This is a lower bound: an agent working under a person's own account with no matching branch, author or label is not detected

Parameter Type Required Description
org_id integer yes Sourcebee org ID to query

Agent access is included with every Sourcebee seat.

See pricing