Groups

Groups represent aggregated errors. You can list, filter, resolve, and mute them via the API.

List Groups for a Project

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

This endpoint is commonly used to build internal dashboards or scripts that need to count or iterate over issues per device, environment, or other tags.

Filtering and Search

The recommended way to filter and search groups is with the query parameter. It supports a rich search syntax that lets you combine status, severity, server/device names, arbitrary tags, environments, and free-text search (including negation and OR) in a single parameter.

Common use case — reading issues for a specific device/server:

curl "https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups?query=server_name:%22eagle-618d24%22" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

You can also combine it with status:

curl "https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups?query=is:unresolved+server_name:eagle-618d24" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Query Syntax

The query value can contain any combination of the following:

You can mix filters and free text:

• Unresolved errors from a specific device containing “timeout”: ?query=is:unresolved server_name:eagle-618d24 timeout
• Production errors with a particular tag: ?query=environment:production tags.region:eu-west PaymentError
• All non-error, non-warning groups from a server: ?query=!is:error,warning server_name:foo
• Negated status + free text: ?query=!is:resolved "payment failed"

Negation (!is:...) is supported for both status and severity filters. Comma syntax provides OR semantics within a single is: or !is: clause (most useful for severities). Status negation is automatically inverted (e.g. !is:resolved behaves like is:unresolved). Last filter of a given type wins if duplicated.

Other List Parameters

Example for unresolved groups (using the simple ?resolved= filter):

curl "https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups?resolved=false&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Example combining modern query syntax (with negation and severity OR) with time range and pagination:

curl "https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups?query=!is:resolved+is:error,warning+server_name:%22eagle-618d24%22&since=2026-05-01&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Format

{
  "groups": [
    {
      "id": 42,
      "project_id": 1,
      "error_type": "NoMethodError",
      "error_message": "undefined method `foo' for nil:NilClass",
      "culprit": "OrdersController#create",
      "fingerprint": "...",
      "severity": "error",
      "occurred_at": "2026-05-20T10:12:34Z",
      "first_occurred_at": "2026-05-20T10:12:34Z",
      "last_occurred_at": "2026-05-20T14:55:01Z",
      "reports_count": 17,
      "notes_count": 2,
      "resolved_at": null,
      "resolver_id": null,
      "muted_at": null,
      "muter_id": null,
      "muted_until": null,
      "muted_until_reports_count": null,
      "resolved": false,
      "muted": false,
      "created_at": "2026-05-20T10:12:34Z",
      "updated_at": "2026-05-20T14:55:01Z"
    }
  ],
  "next_cursor": 41,
  "has_more": true
}

See Pagination for how to use next_cursor and limit.

The severity field on each group is the highest severity ever observed for reports in that group (fatal, error, warning, info, or debug).

The mute fields describe the group’s current active mute:

• muted is true when notifications are currently suppressed.
• muted_until is set for time-based snoozes.
• muted_until_reports_count is set for occurrence-based mutes. It stores the total reports_count at which notifications resume, not the additional count originally requested.

To see per-occurrence details for a group (including server_name, tags, environment, user info, request context, etc.), use the Reports endpoints under the group.

Resolve a Group

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/resolve \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY"

Unresolve a Group

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/resolve \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

Mute a Group

Mute a group forever by omitting a request body:

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/mute \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY"

Mute a group until a number of additional occurrences by passing a positive occurrences value:

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/mute \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"occurrences": 10}'

If the group currently has reports_count: 17, the example above sets muted_until_reports_count to 27. Notifications resume when the group reaches that total report count. Actions that only change state return 204 No Content.

Unmute a Group

Unmuting clears permanent, time-based, and occurrence-based mute conditions.

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/mute \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

Bulk Resolve

Resolve multiple groups in the same project. Groups that are already resolved are skipped; the response reports how many groups were changed.

For bulk resolve, unresolve, mute, and unmute, the groups changed are the group_ids in the request body.

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/bulk_resolve \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_ids": [123, 456, 789]}'

{
  "processed": 3
}

Bulk Unresolve

Re-open multiple resolved groups. Groups that are already unresolved are skipped.

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/bulk_resolve \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_ids": [123, 456, 789]}'

{
  "processed": 3
}

Bulk Mute

Mute multiple groups in the same project. REST bulk mute creates permanent mutes. Groups that are already muted are skipped.

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/bulk_mute \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_ids": [123, 456, 789]}'

{
  "processed": 3
}

Bulk Unmute

Unmute multiple groups. This clears permanent, time-based, and occurrence-based mute conditions. Groups that are already unmuted are skipped.

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/bulk_mute \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_ids": [123, 456, 789]}'

{
  "processed": 3
}

Bulk Merge

Merge multiple source groups into a target group. The target group is identified by GROUP_ID in the URL; the request body lists the groups to merge into it.

curl https://your-telebugs-instance.com/api/telebugs/v1/projects/PROJECT_ID/groups/GROUP_ID/bulk_merge \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_ids": [456, 789]}'

{
  "processed": 2,
  "merged_into_id": 123
}

The API rejects attempts to merge a group into itself or to merge groups that have already been merged.