Investigations
Version: 5.3 | Last updated: 2026-11-13
An investigation is how Bluebox goes deep on a problem. Where chat gives you a fast answer, an investigation works the problem end-to-end: it traces the issue through your service topology, forms and tests hypotheses, assembles evidence from your live telemetry, and hands back a structured, evidence-backed result you can act on or hand straight to your coding agent.
Where to start an investigation
There are three ways in, depending on what you already know:
- From a finding. When Bluebox has already detected a problem, open the Overview page and select Investigate on the finding's row. Bluebox starts with the finding's context already loaded, which is the fastest path.
- From the Investigations page. Open Investigations from the sidebar, select New investigation, and describe the incident in your own words: paste in an error, name a service that's misbehaving, or ask what's wrong. Use this when you have a symptom but no finding yet. (You can start the same way from the Overview page.)
- From a script or CI job. Call the API with your personal access token. See Start an investigation from the API.
The clearer your description, the sharper the investigation. Copying the title and body of an existing GitHub issue into the prompt is a good starting point.
An investigation needs your observability data, so your workspace must have an observability backend connected. Without one, Bluebox does not start the investigation. It shows No observability backend connected with a link to Setup, where you connect one.
Start an investigation from the API
Send the text to investigate to POST /v1/investigations:
curl -X POST "https://<your-bluebox-host>/v1/investigations" \
-H "Authorization: Bearer $BLUEBOX_TOKEN" \
-H "X-Bluebox-Workspace: ws_31qyqBsktp73Z6al9w9jeu" \
-H "Content-Type: application/json" \
-d '{"description": "Checkout latency doubled after the 14:00 deploy", "ref": "ci-run-4711"}'
The ws_... ID is an example of the format. Use the ID of a workspace you belong to.
The response is 201 with the new investigation as a task. The request takes two fields. Any other field returns 400.
description(required): what to investigate, such as an alert, a message, an incident report, or a description of what you see. It must not be blank. It must fit in 64 KB together with theref. About 65,000 plain characters fit. Characters that JSON escapes, such as<,>,&, and line breaks, take more room. A largerdescriptionreturns400.ref(optional): your own key for this investigation, such as a CI run ID. It must not be blank when you send it.
The id in the response is the raw UUID. To check on the investigation, send that id to GET /v1/investigations/<id>. Reads also accept the task_... form that the list and the UI show. Both forms identify the same investigation.
You cannot choose the agent, model, or prompt. Bluebox runs its investigation agent with the agent's own default model. If the agent has none, it uses your workspace's default model, and then the deployment's default. The investigation belongs to you and follows your workspace's default sharing for investigations, the same as one you start in the UI.
Use a personal access token from Account → Access tokens. It has no scopes and is not a platform token for your observability platform. Session cookies also work. Service tokens and scoped tokens are refused.
The token does not choose the workspace. Without an X-Bluebox-Workspace header, the investigation runs in your default workspace: your preferred workspace, then the one you used last, then the only one you belong to. If you belong to several workspaces, send the header. With a token, the header takes the workspace ID in the ws_... form or the raw UUID. A workspace slug does not work with a token.
Repeat a call safely
- Same
refwhile it runs. If your own investigation with thatrefis still running, the call returns201with that investigation and starts no new one. You can retry a failed CI step without paying for a second run. - Same
refafter it ends. The call starts a new investigation. - No
ref. Every call starts a new investigation, even with identical text.
Error responses
400: the request is invalid, or no workspace could be selected because you sent noX-Bluebox-Workspaceheader and have no default workspace.403: the token is scoped, orX-Bluebox-Workspacedoes not name a workspace you are an active member of (workspace_forbidden).409: a colleague is already investigating under the samerefand shared it with the workspace. The response names the running investigation.422: your workspace has no observability backend connected. Connect one in Setup.429: your workspace reached a usage limit, such as the daily number of investigations or the number running at once.
When someone is already investigating
If a colleague is already investigating the same incident and has shared that investigation with the workspace, Bluebox tells you before starting a second one. Instead of an error you get a choice, showing the running investigation's title and when it started:
- Open existing investigation takes you to it, so you can follow along and read the evidence as it arrives. You get read access—the member who started it stays in control of it.
- Start mine anyway creates your own investigation into the same incident. Use this when you need a separate line of inquiry, or when the running one is about to finish. A second investigation counts against your workspace's usage the same as any other, so choose it deliberately.
Two cases never produce this choice. If the match is your own still-running investigation, Bluebox opens that one for you rather than starting a duplicate. If the match is a colleague's investigation that has not been shared, Bluebox says nothing about it and starts yours as usual.
What Bluebox does
Bluebox works through the problem in visible phases (getting situational context, forming and testing hypotheses, investigating the evidence, and reporting) and streams its progress to the investigation timeline as it goes, with a short summary for each phase it completes. You can watch the evidence it gathers build up in real time, keep the tab open, or come back to it later. If your workspace has multiple repositories connected, Bluebox draws context from all of them—you do not need to specify which one.
Selective preview
During the hypothesis-testing phase, Bluebox may pursue several hypotheses in parallel. Each runs its own evidence-gathering stream and returns an evidence-backed finding; Bluebox synthesizes these findings into the final root-cause report.
What you get
When an investigation finishes, it produces an evidence-backed root-cause report on the investigation's page:
- Root cause—what went wrong, stated plainly.
- Evidence—the specific telemetry behind each step of the diagnosis, not a log pattern-match. Every claim traces back to a signal.
- Affected services and endpoints—where the problem shows up in your topology.
- A recommended fix—concrete guidance you can implement yourself or hand to your coding agent.
The report is shown as one Investigation Report card, divided into sections (Summary, Impact, Root Cause, Recommendation, Evidence, and more) that you can expand or collapse individually. Summary, Impact, Root Cause, and Recommendation start open so the story and the recommended fix are visible at a glance; Evidence and Investigation Metadata start collapsed, and you expand them when you need the detail. Each section has two controls: the star icon pins it to the investigation's pinned list at the top of the page, so the parts you care about stay within reach (select the star again to unpin); the copy control puts that section's text on your clipboard to paste elsewhere. Pins belong to the investigation, so anyone you share it with sees the same pinned sections. Read-only members can read and copy every section and see the pins, but only the investigation's owner or the workspace owner can pin and unpin.
When a recommended action follows from one of the hypotheses in the root-cause section, it shows a From H1 label. Select the label (or focus it and press Enter or Space) to read that hypothesis's title, description, and verdict in a small card without scrolling to the root-cause section. Select an evidence id in the card to jump to that item in the Evidence section. Press Escape or select outside the card to close it. If the action's hypothesis can't be found in the report, the label stays plain text.
When an Evidence item cites an earlier investigation, it shows that investigation's ID as a link. Select the link to open it. You can open it only if you have read access to it.
Selective preview
You can also pin individual messages and evidence details from the conversation. Whatever you pin there collects in a Pinned section of the report, below the summary. Each entry shows its first line; select it to read the full message in place, or use the unpin control to remove it. The section stays hidden until you pin something, and the same owner rules apply—read-only members see the pins but cannot remove them.
If an investigation was shared with you and its owner never started a chat, the chat pane shows "No chat activity yet" and a note that you have read-only access and only the owner can start a chat. There is no message box in that case, because read-only members can't reply.
Bluebox also files the result as a GitHub issue in your connected repository for actionable findings, so it lives where your team already works. You can comment on it, assign it, or paste it straight into a coding agent to open a pull request. Whether an issue is filed follows the workspace's GitHub issue policy (smart by default; always or never available): smart files actionable findings and skips inconclusive runs and repeat firings of an already-open problem. Workspace owners set this policy under Settings → Investigations; other members see the current value. Bluebox skips public repositories and ones whose visibility can't be confirmed, whatever the policy says. When writes to public repositories are turned on for your workspace (for example, during a workshop), it files there too, and anyone can read what it files. It also skips an archived repository, which GitHub keeps read-only. When Bluebox skips the connected repository, the investigation report says that no issue was filed and why. The filed issue's link sits in the Summary section next to a label that shows whether the issue is Open or Closed. Bluebox reads the state from GitHub when the report opens. The label catches up within a couple of minutes after your team closes the issue, and within about 15 minutes after your team reopens it. The label shows Unknown when Bluebox can't tell: the issue is in a repository your workspace hasn't connected, you can't use the GitHub connection, the link isn't a GitHub issue, or GitHub doesn't answer. Your coding agent can pull the investigation's full context on demand while it works the fix.
What to investigate
Reach for an investigation whenever you need a diagnosis backed by evidence rather than a quick answer:
- Something you just shipped that's behaving differently in production than it did in testing.
- A spike in errors or latency on a service, especially after a deploy.
- A recurring failure you've seen in the logs but haven't traced to a cause.
- An open GitHub issue describing unexpected behavior in production.
- A user-reported problem where you have a symptom but not the source.
For quick lookups and exploration ("what are the top findings right now", "is checkout healthy"), use chat or bluebox ask instead, and open an investigation when you need the structured result.
Configure auto-investigations
Workspace owners can configure Bluebox to start an investigation automatically for every new incoming finding, without waiting for a manual trigger. Open Settings → Investigations to turn this on.
When you turn on auto-investigations, Bluebox warns you that every new finding starts a run against your usage quota. After you confirm, a Daily budget limit slider appears, set to 80 percent by default. When your workspace reaches that percentage of its daily AI quota, auto-investigations pause until the next day. Manual investigations are never paused by this limit.
To turn off auto-investigations, return to Settings → Investigations and turn the toggle off. Investigations already running continue to completion.
Find an investigation in your list
The Investigations page loads 25 investigations at a time. Searching by title, sorting by a column, and the status and sharing filters all work on the investigations that are loaded.
While more investigations are waiting, a note above the table shows how many are loaded, for example "Searched 25 of 84 loaded. Load more to search the rest." If a search finds nothing in that state, the page says "No matches in the 25 investigations loaded so far."
Select Load more to bring in the next page and extend the search to it. When every investigation is loaded, the note disappears and search covers your whole list.
Investigation states
Your investigations are accessible from the sidebar or the dedicated Investigations page. Common states include:
| State | Meaning |
|---|---|
| Open | Ready to be investigated |
| Investigating | Bluebox is actively working on it |
| Completed | Bluebox finished the investigation and produced its final report, or a workspace owner manually closed it — does not imply the underlying problem was fixed |
| Cancelled | You stopped the investigation before it finished. It cannot be resumed, and its conversation accepts no further messages. |
| Failed | The investigation ended without a result due to an unrecoverable failure (for example, a timeout or an internal error). Re-run it to try again, or archive it. |
| Archived | Closed and stored for reference |