Probes API

Debug probes request additional diagnostic data from SDKs without code changes or redeployment. Always-on probes buffer locally in SDKs on every tier. The API endpoints below manage paid-tier remote activations that can also emit standalone probe_event records.

Probe endpoints accept member token authentication via the Authorization header or an authenticated browser session from the web app.

All probe operations are also available from the project Probes tab in the web app, via the CLI (debugbundle probe activate/list/deactivate), and MCP tools (activate_probe, list_active_probes, deactivate_probe). See CLI Cloud Workflow and MCP Tools.

How Probes Work

You activate a probe with a label pattern, service filter, environment filter, and TTL.
The API creates a passive activation and returns a trigger_token shown once at creation time.
Backend SDKs receive directives through GET /v1/sdk/config; browser and mobile SDKs use startup/lifecycle config checks plus probe_directives piggybacked on successful ingestion responses.
Matching SDK instances emit standalone probe_event records when capture policy allows remote probe events, while always-on probe buffers continue to flush with errors.
Related probe data is merged into context.probe_data in bundles.

Activate Probe

POST /v1/projects/{projectId}/probes/activate

curl -X POST https://api.debugbundle.com/v1/projects/proj_01HXYZ/probes/activate \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "label_pattern": "auth.*",
    "service": "api-gateway",
    "environment": "production",
    "ttl_seconds": 300,
    "trigger_ttl_seconds": 86400
  }'

Request Body:

Field	Type	Required	Description
`label_pattern`	`string`	Yes	Dot-notation label or wildcard, such as `auth.` or ``.
`service`	`string`	No	Scope to a specific service. Defaults to `*`.
`environment`	`string`	No	Scope to a specific environment. Defaults to `*`.
`ttl_seconds`	`number`	Yes	Passive activation lifetime in seconds. Max: `3600` (1 hour).
`trigger_ttl_seconds`	`number`	No	Trigger token validity window. Defaults to `ttl_seconds`. Max: `86400` (24 hours).
`sample_rate`	`number`	No	Reserved sampling control, `0.0` through `1.0`. Defaults to `1.0`.

Response (200):

{
  "activation_id": "550e8400-e29b-41d4-a716-446655440000",
  "label_pattern": "auth.*",
  "service": "api-gateway",
  "environment": "production",
  "expires_at": "2026-05-28T12:00:00.000Z",
  "trigger_expires_at": "2026-05-29T11:00:00.000Z",
  "created_at": "2026-05-28T11:00:00.000Z",
  "trigger_token": "dbundle_probe_..."
}

The trigger_token is returned only once at activation time. Store it immediately; it cannot be retrieved later.

expires_at controls the passive directive window. trigger_expires_at controls how long the trigger token remains valid. Attach the token to a specific request with ?_debug_probe=dbundle_probe_... or X-DebugBundle-Probe-Trigger: dbundle_probe_....

List Active Probes

GET /v1/projects/{projectId}/probes

curl https://api.debugbundle.com/v1/projects/proj_01HXYZ/probes \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

Response (200):

{
  "activations": [
    {
      "activation_id": "550e8400-e29b-41d4-a716-446655440000",
      "label_pattern": "auth.*",
      "service": "api-gateway",
      "environment": "production",
      "expires_at": "2026-05-28T12:00:00.000Z",
      "activated_by": "user@example.com",
      "created_at": "2026-05-28T11:00:00.000Z"
    }
  ]
}

Active probe lists do not include trigger_token; it is shown only at activation time.

If a project downgrades to Free, this list stays readable so preserved remote probe activations remain visible. Activation still returns upgrade_required until the project upgrades again, deactivation remains available as cleanup, and Free-tier SDK config keeps remote_probes_enabled: false.

Deactivate Probe

POST /v1/projects/{projectId}/probes/deactivate

curl -X POST https://api.debugbundle.com/v1/projects/proj_01HXYZ/probes/deactivate \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "activation_id": "550e8400-e29b-41d4-a716-446655440000" }'

Response (200):

{
  "deactivated": {
    "activation_id": "550e8400-e29b-41d4-a716-446655440000",
    "deactivated_at": "2026-05-28T11:10:00.000Z"
  }
}

The activation stops appearing in SDK config and ingestion-response directives after deactivation.

Limits

Constraint	Free	Solo/Team
Always-on probes	Available	Available
Remote activation	Not available	Available
Max concurrent remote activations per project	N/A	5
Passive activation TTL	N/A	1 hour max
Trigger token TTL	N/A	24 hours max

Probe Directives in Ingestion

When active probes exist for a paid-tier project, successful POST /v1/events responses may include piggybacked directives:

{
  "accepted": 1,
  "rejected": 0,
  "errors": [],
  "probe_directives": {
    "active_probes": [
      {
        "activation_id": "550e8400-e29b-41d4-a716-446655440000",
        "label_pattern": "auth.*",
        "service": "api-gateway",
        "environment": "production",
        "expires_at": "2026-05-28T12:00:00.000Z",
        "trigger_expires_at": "2026-05-29T11:00:00.000Z"
      }
    ]
  }
}

Browser and mobile SDKs use these piggybacked directives to avoid aggressive polling. Backend SDKs primarily use GET /v1/sdk/config with ETags.

Next Steps

CLI Cloud Workflow — Manage probes via the CLI
Probes — Probe behavior, limits, and trigger-token usage
Bundles — How probes enrich bundle data
Universal SDK Interface — SDK probe support

Probes API

How Probes Work

Activate Probe

List Active Probes

Deactivate Probe

Limits

Probe Directives in Ingestion

Next Steps

On this page