Say when captcha task events carry a challenge_id

[archandatta]

Summary

The captcha telemetry docs are otherwise accurate for the shipped behavior, including after the relay start-event emit. One line in the correlation section isn't: it tells you to group solver tasks by challenge_id without saying which task events set one.

challenge_id comes from tracking the challenge widget in the page — the same tracking that produces captcha_challenge_result. A task the automatic solver runs outside that tracking reports a task_id only, and that covers the common types on a stealth session. So a reader can hit a page that emits a captcha_challenge_result with a challenge_id and task events that carry none, and find the documented grouping silently inapplicable. The section hedged with "when the identifiers are present" but never said when they aren't.

This adds one paragraph saying which identifier to rely on, and softens "group every task" to match it.

Why now

captcha_solve_started was documented as part of the category before every producer emitted it. It now flows on the path that handles most stealth-session captchas, which makes the correlation advice load-bearing for exactly the agents that consume it, so the gap is worth closing.

Scope

Everything else in the section checks out against the shipped events and was left alone:

• The three event types, their scopes, and the challenge status meanings match the schema.
• captcha_solve_result statuses (success / failure / timeout / abandoned) match the spec enum.
• "Challenge results are currently emitted for visible reCAPTCHA v2, hCaptcha, and press-and-hold challenges" matches what the in-page observer covers.
• The ordering and best-effort-delivery caveats, and "use duration_ms rather than timestamps," match how the events are published.
• "This doesn't mean a solve is currently in flight" on captcha_solve_started is correct and worth keeping — a start only means a task was accepted.
• The data-sensitivity table already covers task_id / challenge_id and the host and path.

No new events, fields, or pages: the event reference itself comes from the OpenAPI spec, where challenge_id is already optional.

Testing

Prose-only change to one page. No links added, so the broken-links workflow is unaffected. Rendering not checked in a local mintlify dev — the edit adds a plain paragraph to an existing section with no new MDX constructs.

---

Note

Low Risk
Documentation-only edit to captcha telemetry correlation guidance; no runtime or API behavior changes.

Overview
Updates the Correlate captcha tasks and challenges section in categories.mdx so readers know when challenge_id is present on task events.

The intro now says to group the tasks for a challenge (not “every” task), matching cases where some tasks never get a challenge_id. A new paragraph explains that all task events have task_id, but challenge_id only appears when the in-page widget tracking path is active—the same path that can emit captcha_challenge_result. Automatic solver work outside that tracking is task_id-only, so those events cannot be joined to a challenge result even if one exists on the page. The doc directs pairing start/result on task_id and using challenge_id for grouping only when it is set.

^{Reviewed by Cursor Bugbot for commit 97f9b49. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Sep 1, 2026, 2:08 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[cursor]

Stale comment

Risk assessment: Very Low

Re-evaluated on head 76561a5. The three-dot diff is unchanged: a single documentation file, browsers/telemetry/categories.mdx (+3 / −1).

What changed in the file:

• One sentence in Correlate captcha tasks and challenges no longer says to group every task by challenge_id.
• A new paragraph states that task events always have task_id, and that challenge_id is only set when in-page challenge-widget tracking is active.

This is published docs copy only. No runtime, API, OpenAPI, config, CI, or infrastructure files change. Blast radius is limited to that section of the telemetry categories page. No CODEOWNERS file exists, so codeowner review is not required.

This automation already approved this same commit. Risk did not increase, so the existing approval stands and is not being re-issued.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[masnwilliams]

lgtm

[cursor]

Risk assessment: Very Low

Re-evaluated after the latest synchronize (head 97f9b49, a merge of main into the PR branch). The three-dot diff is unchanged: one documentation file, browsers/telemetry/categories.mdx (+3 / −1).

What the file changes:

• In Correlate captcha tasks and challenges, "group every task" is now "group the tasks".
• A new paragraph states that task events always have task_id, and that challenge_id is only set when in-page challenge-widget tracking is active.

This is published docs copy only. No runtime, API, OpenAPI, config, CI, or infrastructure files change. Blast radius is limited to that section of the telemetry categories page. No CODEOWNERS file exists, so codeowner review is not required.

Risk did not increase. The PR is already approved, so that approval stands and is not being re-issued.

  

_{Sent by Cursor Automation: Assign PR reviewers}