API reference: Documentation for the Honeybadger Data (REST) API and reporting APIs. # API documentation > Complete API documentation for Honeybadger's REST and reporting APIs. Honeybadger’s APIs allow you to report exceptions from your applications, monitor your scheduled tasks, and retrieve and update the data we generate from your app’s errors. ## Reporting [Section titled “Reporting”](#reporting) These endpoints are the core of Honeybadger and how you get your data into our system. [Exceptions](/api/reporting-exceptions/)`api.honeybadger.io/v1/notices` [Check-Ins](/api/reporting-check-ins/)`api.honeybadger.io/v1/check_in/:id` [Deployments](/api/reporting-deployments/)`api.honeybadger.io/v1/deploys` [Source Maps](/api/reporting-source-maps/)`api.honeybadger.io/v1/source_maps` [Events](/api/reporting-events/)`api.honeybadger.io/v1/events` ## Data API [Section titled “Data API”](#data-api) The Data API can be used to access data stored in your Honeybadger account and to make changes to your account data. [Faults](/api/faults/) [Dashboards](/api/dashboards/) [Uptime](/api/uptime/) [Check-Ins](/api/check-ins/) [Comments](/api/comments/) [Deployments](/api/deployments/) [Projects](/api/projects/) [Teams](/api/teams/) [Environments](/api/environments/) [Accounts](/api/accounts/) [Status Pages](/api/status-pages/) # Accounts API reference > API reference for managing account information and users. In Honeybadger, all resources are tied to an account. A user may belong to one or more accounts (for instance, you can have a work account and a personal account). The Accounts API allows you to programmatically fetch details about your accounts. ## Get all accounts [Section titled “Get all accounts”](#get-all-accounts) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ ``` Returns a list of all accounts the authenticated user belongs to. ```json { "results": [ { "id": "Me3upk", "email": "homerjsimpson@gmail.com", "name": "homer", "active": true, "parked": false }, { "id": "9bYfrm", "email": "homer.j@simpsons.io", "name": "Work", "active": true, "parked": false } ], "links": { "self": "http://localhost:3000/v2/accounts" } } ``` ## Get info for one account [Section titled “Get info for one account”](#get-info-for-one-account) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID ``` Returns info about an account, including the quota consumption for the current month. Each of the three sets of quota info is returned as an array of arrays, with one date & count pair for each day of the month, starting at midnight UTC on the first of the month. The different types of stats are as follows: * Stored: The number of error notifications saved and available for display in the UI * Limited: The number of notifications that were discarded due to throttling (429 responses) * Ignored: Notifications discarded as a result of errors being flagged as ignored in the UI The quota\_consumed value is a percentage, so `0.75` would mean 75% of the month’s quota has been consumed. The quota resets at the first of the month. ```json { "id": "Me3upk", "email": "homerjsimpson@gmail.com", "name": "homer", "active": true, "parked": false, "quota_consumed": 0.75, "api_stats": { "stored": [ [ 1648767600, 116 ], [ 1648771200, 65 ], ... ], "limited": [], "ignored": [] } } ``` ## Get a list of account users or user details [Section titled “Get a list of account users or user details”](#get-a-list-of-account-users-or-user-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID/users curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID/users/ID ``` Returns all the users or a single user for the given account: ```json { "results": [ { "id": 1, "role": "Owner", "name": "", "email": "westley@example.com" } ] } ``` ## Update a user [Section titled “Update a user”](#update-a-user) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"user":{"role":"Admin"}}' https://app.honeybadger.io/v2/accounts/ID/users/ID ``` The list of valid fields is as follows: | Field name | Type | Description | | ---------- | ------ | ----------------------------------------------- | | `role` | string | One of “Member”, “Billing”, “Admin”, or “Owner” | ## Remove a user from the account [Section titled “Remove a user from the account”](#remove-a-user-from-the-account) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/accounts/ID/users/ID ``` ## Create an invitation for a user to join an account [Section titled “Create an invitation for a user to join an account”](#create-an-invitation-for-a-user-to-join-an-account) ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \ -d '{"invitation":{"email":"inigo@example.com"}}' \ https://app.honeybadger.io/v2/accounts/ID/invitations ``` You can specify these fields: | Field name | Type | Description | | ---------- | ------ | --------------------------------------------------------- | | `email` | string | The invited user’s email address. | | `role` | string | One of “Member”, “Billing”, “Admin”, or “Owner” | | `team_ids` | array | Array of team ids to which the invited user will be added | Returns the created user invitation: ```json { "id": 9, "email": "inigo@example.com", "created_by": { "email": "westley@example.com", "name": "Westley" }, "accepted_by": null, "role": "Member", "accepted_at": null, "created_at": "2013-01-08T15:42:16Z", "team_ids": [] } ``` ## Update an account invitation [Section titled “Update an account invitation”](#update-an-account-invitation) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' \ -d '{"invitation":{"role": "Admin"}}' \ https://app.honeybadger.io/v2/accounts/ID/invitations/ID ``` You can specify either of these fields: | Field name | Type | Description | | ---------- | ------ | --------------------------------------------------------- | | `role` | string | One of “Member”, “Billing”, “Admin”, or “Owner” | | `team_ids` | array | Array of team ids to which the invited user will be added | ## Get an account invitation list or account invitation details [Section titled “Get an account invitation list or account invitation details”](#get-an-account-invitation-list-or-account-invitation-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID/invitations curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID/invitations/ID ``` Returns a list of account invitations or a single account invitation for the given account: ```json { "results": [ { "id": 9, "email": "inigo@example.com", "created_by": { "email": "westley@example.com", "name": "Westley" }, "accepted_by": { "email": "inigo@example.com", "name": "Inigo Montoya" }, "role": "Member", "accepted_at": "2013-01-08T15:42:41Z", "created_at": "2013-01-08T15:42:16Z", "team_ids": [] } ] } ``` ## Delete an account invitation [Section titled “Delete an account invitation”](#delete-an-account-invitation) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/accounts/ID/invitations/ID ``` # Alarms API reference > API reference for managing Insights alarms with endpoints to create, read, update, and delete alarms and view their trigger history. The Alarms API lets you programmatically manage [Insights alarms](/guides/insights/alarms/). All alarm endpoints are scoped to a project. Notification channels for alarms are managed in the Honeybadger UI and can’t be set via the API. ## Get an alarm list or alarm details [Section titled “Get an alarm list or alarm details”](#get-an-alarm-list-or-alarm-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/alarms curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/alarms/ID ``` The list endpoint returns results in a `results` array. The detail endpoint returns a single alarm: ```json { "id": "8f0dc2b1-4d9e-4b6a-9c3f-2e7a51d0c8aa", "name": "High error rate", "description": "Triggers when error count exceeds 100 in 5 minutes", "state": "ok", "query": "filter event_type::str == \"notice\"", "stream_ids": ["a1b2c3d4e5f6"], "evaluation_period": "5m", "lookback_lag": "1m", "trigger_config": { "type": "alert_result_count", "config": { "operator": "gt", "value": 100 } }, "error": null, "last_checked_at": "2026-02-04T09:10:00Z", "next_check_at": "2026-02-04T09:15:00Z", "created_at": "2026-01-31T14:22:18Z", "updated_at": "2026-02-04T09:11:05Z", "url": "https://app.honeybadger.io/projects/1/insights/alarms/42", "project_id": 1 } ``` The response includes: | Field name | Type | Description | | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The alarm’s UUID. Use this value in URLs for show, update, delete, and history requests. | | `name` | string | The alarm name. | | `description` | string | The alarm description. | | `state` | string | The alarm’s current state: `"ok"` (trigger condition not met), `"alarm"` (triggered), or `"initial"` (not yet evaluated). | | `query` | string | The [BadgerQL query](/guides/insights/badgerql/) the alarm evaluates. | | `stream_ids` | array | The IDs of the Insights streams the alarm queries. | | `evaluation_period` | string | How often the alarm is evaluated, as a duration string (`"5m"`, `"1h"`, `"1d"`). | | `lookback_lag` | string | The delay before each evaluation to allow data to arrive (`"1m"`, `"0s"`). | | `trigger_config` | object | The trigger condition. See [Trigger config](#trigger-config). | | `error` | string | The error message if the alarm’s query failed to execute; `null` otherwise. | | `last_checked_at` | string | ISO 8601 timestamp of the last evaluation. | | `next_check_at` | string | ISO 8601 timestamp of the next scheduled evaluation. | | `created_at` | string | ISO 8601 timestamp. | | `updated_at` | string | ISO 8601 timestamp. | | `url` | string | A link to the alarm in the Honeybadger UI. | | `project_id` | integer | The project the alarm belongs to. | ## Create an alarm [Section titled “Create an alarm”](#create-an-alarm) ```bash curl -u AUTH_TOKEN: \ -X POST \ -H 'Content-type: application/json' \ -d '{ "alarm": { "name": "High error rate", "description": "Triggers when error count exceeds 100 in 5 minutes", "query": "filter event_type::str == \"notice\"", "evaluation_period": "5m", "lookback_lag": "1m", "trigger_config": { "type": "alert_result_count", "config": { "operator": "gt", "value": 100 } } } }' \ https://app.honeybadger.io/v2/projects/ID/alarms ``` Returns `201 Created` with the alarm JSON shown above. The request body must be wrapped in a top-level `alarm` object. These fields can be provided: | Field name | Type | Description | | ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Required. The alarm name. | | `query` | string | Required. A [BadgerQL query](/guides/insights/badgerql/) that returns the data to monitor. The alarm system wraps the query to count matching results per evaluation period, so a bare `filter` works — see [Query guidelines](#query-guidelines) below. | | `evaluation_period` | string | Required. How often the alarm is evaluated, as a duration string (`"5m"`, `"1h"`, `"1d"`). Minimum `1m`, maximum less than a week. | | `trigger_config` | object | Required. The condition that triggers the alarm. See [Trigger config](#trigger-config). | | `description` | string | Optional description. | | `stream_ids` | array | Optional list of [Insights stream IDs](/api/streams/) to query. If omitted, the alarm queries all streams on the project. IDs that don’t belong to the project are ignored; if that leaves the list empty, the request fails with a `422`. Note these are stream IDs, not slugs — `"default"` is a slug and is ignored. | | `lookback_lag` | string | Optional delay before each evaluation to allow data to arrive (`"1m"`, `"0s"`). | A `422 Unprocessable Entity` response with an `errors` key is returned when the alarm is invalid — for example, a missing required field, an invalid BadgerQL query, or an unknown trigger type. ### Trigger config [Section titled “Trigger config”](#trigger-config) The `trigger_config` object defines when the alarm transitions to the alarm state: | Field name | Type | Description | | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- | | `type` | string | The trigger type. Currently `"alert_result_count"`, which triggers based on the count of results returned by the query. | | `config.operator` | string | The comparison operator: `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"eq"`, or `"neq"`. | | `config.value` | integer | The threshold to compare the result count against. Must be >= 0. | Some examples: ```json // Trigger when more than 50 events match the query { "type": "alert_result_count", "config": { "operator": "gt", "value": 50 } } // Trigger when no events match (e.g., a missing heartbeat) { "type": "alert_result_count", "config": { "operator": "eq", "value": 0 } } // Trigger when any events match { "type": "alert_result_count", "config": { "operator": "neq", "value": 0 } } ``` ### Query guidelines [Section titled “Query guidelines”](#query-guidelines) The alarm system automatically wraps the query to count results per evaluation period, so the query should filter and/or aggregate events, and the system handles the final counting: ```plaintext filter event_type::str == "notice" filter status::int >= 500 filter event_type::str == "request.handled" and duration::int > 5000 ``` Queries with `stats` also work — the system counts the result rows: ```plaintext filter event_type::str == "notice" | stats count() as count by fault_id::int ``` ## Update an alarm [Section titled “Update an alarm”](#update-an-alarm) ```bash curl -u AUTH_TOKEN: \ -X PUT \ -H 'Content-type: application/json' \ -d '{ "alarm": { "name": "High error rate", "query": "filter event_type::str == \"notice\"", "evaluation_period": "10m", "trigger_config": { "type": "alert_result_count", "config": { "operator": "gt", "value": 100 } } } }' \ https://app.honeybadger.io/v2/projects/ID/alarms/ID ``` Returns `204 No Content` on success. The request body uses the same fields as [Create an alarm](#create-an-alarm). The submitted definition replaces the existing one, so include every field — even the ones you aren’t changing. ## Delete an alarm [Section titled “Delete an alarm”](#delete-an-alarm) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/alarms/ID ``` Returns `204 No Content` on success. ## Get alarm trigger history [Section titled “Get alarm trigger history”](#get-alarm-trigger-history) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/alarms/ID/history ``` Returns the alarm’s past evaluations that changed its state: ```json { "triggers": [ { "id": "d4c8a2f6-3b1e-4f7a-8c5d-9e0b2a6f1c3e", "state": "alarm", "result": { "count": 127 }, "created_at": "2026-02-04T09:05:00Z" } ], "links": { "self": "...", "prev": "...", "next": "..." } } ``` Each entry in the `triggers` array includes: | Field name | Type | Description | | ------------ | ------ | ---------------------------------------------------------------- | | `id` | string | The trigger event ID. | | `state` | string | The state after the evaluation: `"ok"`, `"alarm"`, or `"error"`. | | `result` | object | The query result that caused the state change. | | `created_at` | string | ISO 8601 timestamp of the evaluation. | Use the `page` query parameter to paginate; the `links` object contains URLs for the previous and next pages. # Check-ins API reference > API reference for managing check-ins with endpoints to create, read, update, and delete scheduled task and cron monitors. ## Get a check-in list or check-in details [Section titled “Get a check-in list or check-in details”](#get-a-check-in-list-or-check-in-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/check_ins curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/check_ins/ID ``` Returns a list of check-ins or a single check-in for a project. There are two different types of check-ins, simple or cron, and the response varies a bit between the two types. ### Simple check-in [Section titled “Simple check-in”](#simple-check-in) ```json { "state": "pending", "schedule_type": "simple", "reported_at": null, "expected_at": null, "missed_count": 0, "grace_period": "5 minutes", "id": "XXXXXX", "name": "Hourly clean up", "slug": "hourly-clean-up", "url": "https://api.honeybadger.io/v1/check_in/XXXXXX", "report_period": "1 hour" } ``` ### Cron check-in [Section titled “Cron check-in”](#cron-check-in) ```json { "state": "reporting", "schedule_type": "cron", "reported_at": "2018-01-16T12:36:11Z", "expected_at": "2018-01-17T12:36:11Z", "missed_count": 0, "grace_period": "", "id": "YYYYYY", "name": "Hourly check", "slug": "hourly-check", "url": "https://api.honeybadger.io/v1/check_in/YYYYYY", "cron_schedule": "30 * * * *", "cron_timezone": "UTC" } ``` ## Create a check-in [Section titled “Create a check-in”](#create-a-check-in) ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"check_in":{"name":"Daily reports", "report_period":"1 day", "schedule_type":"simple"}}' https://app.honeybadger.io/v2/projects/ID/check_ins ``` This endpoint returns either the simple or cron check-in response described above, depending on the type of check-in you create. These fields can be provided: | Field name | Type | Description | | -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | | | slug | string | Optional identifier for more human-friendly check-in URL. | | schedule\_type | string | Valid values are “simple” or “cron”. If you specify “cron”, then the “cron\_schedule” field is required. | | report\_period | string | For simple check-ins, the amount of time that can elapse before the check-in is reported as missing. E.g., “1 day” would require a hit to the API daily to maintain the “reporting” status. Valid time periods are “minute”, “hour”, “day”, “week”, and “month”: “5 minutes”, “7 days”, etc. | | grace\_period | string | The amount of time to allow a job to not report before it’s reported as missing. Valid values are the same as the report\_period field. | | cron\_schedule | string | For a `schedule_type` of “cron”, the [cron-compatible string](https://en.wikipedia.org/wiki/Cron#Overview) that defines when the job should be expected to hit the API. | | cron\_timezone | string | The timezone setting for your server that is running the cron job to be monitored. The default value is “UTC”. Valid timezone values are listed [here](/api/check-ins/timezones/). | ## Update a check-in [Section titled “Update a check-in”](#update-a-check-in) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"check_in":{"name":"Updated check-in name"}}' https://app.honeybadger.io/v2/projects/ID/check_ins/ID ``` The fields listed in the previous section other than `schedule_type` can be updated. In other words, the schedule type can’t be changed. The `report_period` field is only valid for simple check-ins, and the `cron_schedule` and `cron_timezone` fields are only valid for cron check-ins. ## Update all check-ins [Section titled “Update all check-ins”](#update-all-check-ins) Caution Use this endpoint with caution, as it will delete all existing check-ins if you send an empty payload. ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"check_ins":[{"name":"Updated check-in name", "slug":"my-slug"}]}' https://app.honeybadger.io/v2/projects/ID/check_ins ``` Similar to updating a single check-in, this endpoint can be used to update multiple check-ins at once. All check-ins need to be unique by slug and by name (if provided). Any check-ins that do not have a matching slug or name will be created, and any check-ins that are not present in the request will be deleted. The results will be an array of the updated check-ins and any check-ins that were created or deleted. The response will look like this: ```json { "results": [ { "operation": "update", "slug": "my-changed-slug", "success": true }, { "operation": "create", "slug": "my-changed-slug", "success": false, "errors": ["Slug is not unique"] }, { "operation": "delete", "slug": "my-deleted-slug", "success": true } ] } ``` ## Delete a check-in [Section titled “Delete a check-in”](#delete-a-check-in) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/check_ins/ID ``` # Check-in timezone values > Complete list of supported timezones for Honeybadger check-in scheduling and cron monitoring configuration. Use the friendly name (like Pacific Time (US & Canada) instead of America/Los\_Angeles) when working with the API. The other labels are provided here for search-ability. 🙂 | Value for `cron_timezone` (use this) | AKA (don’t use this) | | ------------------------------------ | ------------------------------- | | UTC | Etc/UTC | | Abu Dhabi | Asia/Muscat | | Adelaide | Australia/Adelaide | | Alaska | America/Juneau | | Almaty | Asia/Almaty | | American Samoa | Pacific/Pago\_Pago | | Amsterdam | Europe/Amsterdam | | Arizona | America/Phoenix | | Astana | Asia/Dhaka | | Athens | Europe/Athens | | Atlantic Time (Canada) | America/Halifax | | Auckland | Pacific/Auckland | | Azores | Atlantic/Azores | | Baghdad | Asia/Baghdad | | Baku | Asia/Baku | | Bangkok | Asia/Bangkok | | Beijing | Asia/Shanghai | | Belgrade | Europe/Belgrade | | Berlin | Europe/Berlin | | Bern | Europe/Zurich | | Bogota | America/Bogota | | Brasilia | America/Sao\_Paulo | | Bratislava | Europe/Bratislava | | Brisbane | Australia/Brisbane | | Brussels | Europe/Brussels | | Bucharest | Europe/Bucharest | | Budapest | Europe/Budapest | | Buenos Aires | America/Argentina/Buenos\_Aires | | Cairo | Africa/Cairo | | Canberra | Australia/Melbourne | | Cape Verde Is. | Atlantic/Cape\_Verde | | Caracas | America/Caracas | | Casablanca | Africa/Casablanca | | Central America | America/Guatemala | | Central Time (US & Canada) | America/Chicago | | Chatham Is. | Pacific/Chatham | | Chennai | Asia/Kolkata | | Chihuahua | America/Chihuahua | | Chongqing | Asia/Chongqing | | Copenhagen | Europe/Copenhagen | | Darwin | Australia/Darwin | | Dhaka | Asia/Dhaka | | Dublin | Europe/Dublin | | Eastern Time (US & Canada) | America/New\_York | | Edinburgh | Europe/London | | Ekaterinburg | Asia/Yekaterinburg | | Fiji | Pacific/Fiji | | Georgetown | America/Guyana | | Greenland | America/Godthab | | Guadalajara | America/Mexico\_City | | Guam | Pacific/Guam | | Hanoi | Asia/Bangkok | | Harare | Africa/Harare | | Hawaii | Pacific/Honolulu | | Helsinki | Europe/Helsinki | | Hobart | Australia/Hobart | | Hong Kong | Asia/Hong\_Kong | | Indiana (East) | America/Indiana/Indianapolis | | International Date Line West | Etc/GMT+12 | | Irkutsk | Asia/Irkutsk | | Islamabad | Asia/Karachi | | Istanbul | Europe/Istanbul | | Jakarta | Asia/Jakarta | | Jerusalem | Asia/Jerusalem | | Kabul | Asia/Kabul | | Kaliningrad | Europe/Kaliningrad | | Kamchatka | Asia/Kamchatka | | Karachi | Asia/Karachi | | Kathmandu | Asia/Kathmandu | | Kolkata | Asia/Kolkata | | Krasnoyarsk | Asia/Krasnoyarsk | | Kuala Lumpur | Asia/Kuala\_Lumpur | | Kuwait | Asia/Kuwait | | Kyiv | Europe/Kiev | | La Paz | America/La\_Paz | | Lima | America/Lima | | Lisbon | Europe/Lisbon | | Ljubljana | Europe/Ljubljana | | London | Europe/London | | Madrid | Europe/Madrid | | Magadan | Asia/Magadan | | Marshall Is. | Pacific/Majuro | | Mazatlan | America/Mazatlan | | Melbourne | Australia/Melbourne | | Mexico City | America/Mexico\_City | | Mid-Atlantic | Atlantic/South\_Georgia | | Midway Island | Pacific/Midway | | Minsk | Europe/Minsk | | Monrovia | Africa/Monrovia | | Monterrey | America/Monterrey | | Montevideo | America/Montevideo | | Moscow | Europe/Moscow | | Mountain Time (US & Canada) | America/Denver | | Mumbai | Asia/Kolkata | | Muscat | Asia/Muscat | | Nairobi | Africa/Nairobi | | New Caledonia | Pacific/Noumea | | New Delhi | Asia/Kolkata | | Newfoundland | America/St\_Johns | | Novosibirsk | Asia/Novosibirsk | | Nuku’alofa | Pacific/Tongatapu | | Osaka | Asia/Tokyo | | Pacific Time (US & Canada) | America/Los\_Angeles | | Paris | Europe/Paris | | Perth | Australia/Perth | | Port Moresby | Pacific/Port\_Moresby | | Prague | Europe/Prague | | Pretoria | Africa/Johannesburg | | Puerto Rico | America/Puerto\_Rico | | Quito | America/Lima | | Rangoon | Asia/Rangoon | | Riga | Europe/Riga | | Riyadh | Asia/Riyadh | | Rome | Europe/Rome | | Samara | Europe/Samara | | Samoa | Pacific/Apia | | Santiago | America/Santiago | | Sapporo | Asia/Tokyo | | Sarajevo | Europe/Sarajevo | | Saskatchewan | America/Regina | | Seoul | Asia/Seoul | | Singapore | Asia/Singapore | | Skopje | Europe/Skopje | | Sofia | Europe/Sofia | | Solomon Is. | Pacific/Guadalcanal | | Srednekolymsk | Asia/Srednekolymsk | | Sri Jayawardenepura | Asia/Colombo | | St. Petersburg | Europe/Moscow | | Stockholm | Europe/Stockholm | | Sydney | Australia/Sydney | | Taipei | Asia/Taipei | | Tallinn | Europe/Tallinn | | Tashkent | Asia/Tashkent | | Tbilisi | Asia/Tbilisi | | Tehran | Asia/Tehran | | Tijuana | America/Tijuana | | Tokelau Is. | Pacific/Fakaofo | | Tokyo | Asia/Tokyo | | Ulaanbaatar | Asia/Ulaanbaatar | | Urumqi | Asia/Urumqi | | Vienna | Europe/Vienna | | Vilnius | Europe/Vilnius | | Vladivostok | Asia/Vladivostok | | Volgograd | Europe/Volgograd | | Warsaw | Europe/Warsaw | | Wellington | Pacific/Auckland | | West Central Africa | Africa/Algiers | | Yakutsk | Asia/Yakutsk | | Yerevan | Asia/Yerevan | | Zagreb | Europe/Zagreb | | Zurich | Europe/Zurich | # Comments API reference > API reference for managing error comments with endpoints to create, read, update, and delete resources. ## Get a comment list or comment details [Section titled “Get a comment list or comment details”](#get-a-comment-list-or-comment-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/comments curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/comments/ID ``` Returns a list of comments or a single comment for the given fault with the following format: ```json { "id": 14, "fault_id": 2, "event": null, "source": "unknown", "notices_count": 0, "created_at": "2012-08-22T15:47:26Z", "author": "Inigo", "body": "You killed my father; prepare to die" } ``` ## Create a comment [Section titled “Create a comment”](#create-a-comment) ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"comment":{"body":"My comment"}}' https://app.honeybadger.io/v2/projects/ID/faults/ID/comments ``` The `body` field is the only field that can be included in the payload. ## Update a comment [Section titled “Update a comment”](#update-a-comment) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"comment":{"body":"Updated comment"}}' https://app.honeybadger.io/v2/projects/ID/faults/ID/comments/ID ``` ## Delete a comment [Section titled “Delete a comment”](#delete-a-comment) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/faults/ID/comments/ID ``` # Dashboards API reference > API reference for managing Insights dashboards with endpoints to create, read, update, and delete dashboards and their widgets. The Dashboards API lets you programmatically manage [Insights dashboards](/guides/dashboards/) and their widgets. All dashboard endpoints are scoped to a project. ## Get a dashboard list or dashboard details [Section titled “Get a dashboard list or dashboard details”](#get-a-dashboard-list-or-dashboard-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/dashboards curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/dashboards/ID ``` The list endpoint returns results in a `results` array. The detail endpoint returns a single dashboard: ```json { "id": "abc123", "title": "My Dashboard", "widgets": [ { "id": "4b2e9c1a-7f3d-4a12-9d5e-0b8f6a2c1e4d", "type": "insights_vis", "grid": { "x": 0, "y": 0, "w": 12, "h": 3 }, "presentation": { "title": "Total requests" }, "config": { "query": "filter event_type::str == \"request\" | stats count() by bin()", "vis": { "view": "line" }, "streams": ["default"] } } ], "is_default": false, "shared": true, "default_ts": "P7D", "created_at": "2026-01-31T14:22:18Z", "updated_at": "2026-02-04T09:11:05Z", "project_id": 1 } ``` The response includes: | Field name | Type | Description | | ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The dashboard’s hashid. Use this value in URLs for show, update, and delete requests. | | `title` | string | The dashboard title. | | `widgets` | array | The dashboard’s widgets, in source form (see below). | | `is_default` | boolean | Whether this is the project’s default dashboard. | | `shared` | boolean | Whether the dashboard is shared with other users on the account. Dashboards created via the API are shared. | | `default_ts` | string | The dashboard’s default time range, if set. See `default_ts` under [Create a dashboard](#create-a-dashboard) for accepted values. | | `created_at` | string | ISO 8601 timestamp. | | `updated_at` | string | ISO 8601 timestamp. | | `project_id` | integer | The project the dashboard belongs to. | In the response, each widget’s `config.streams` contains stream *slugs* (for example `"default"` or `"internal"`) rather than numeric stream IDs. Use the same slugs when creating or updating widgets. ## Create a dashboard [Section titled “Create a dashboard”](#create-a-dashboard) ```bash curl -u AUTH_TOKEN: \ -X POST \ -H 'Content-type: application/json' \ -d '{"dashboard":{"title":"My Dashboard","widgets":[]}}' \ https://app.honeybadger.io/v2/projects/ID/dashboards ``` Returns `201 Created` with the dashboard JSON shown above. The request body must be wrapped in a top-level `dashboard` object. These fields can be provided: | Field name | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | string | The dashboard title. | | `widgets` | array | The dashboard’s widgets. See the widget fields below. Pass an empty array to create a dashboard with no widgets. | | `default_ts` | string | Optional default time range. Accepts an ISO 8601 duration (`P1D`, `P7D`, `PT1H`), a keyword (`today`, `yesterday`, `week`, `month`), or a date range (`2024-01-01/2024-01-31`). | ### Widget fields [Section titled “Widget fields”](#widget-fields) Each entry in the `widgets` array describes a single widget. The most common widget type is `insights_vis`, which renders a BadgerQL query as a chart or table: | Field name | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | The widget type, e.g. `"insights_vis"`. Other built-in types include `"alarms"`, `"deployments"`, `"checkins"`, `"uptime"`, and `"errors"`. | | `id` | string | Optional UUID. If omitted, the server generates one. Must be unique within the dashboard. On update, include the existing widget’s `id` to preserve it; omitting it will regenerate the ID. | | `grid` | object | Position and size on the dashboard grid. Keys: `x`, `y`, `w`, `h`. Defaults to `{"x": 0, "y": 0, "w": 12, "h": 3}` if omitted. | | `presentation` | object | Display options. Keys: `title`, `subtitle`. | | `config` | object | Widget-specific configuration. See below. | For `insights_vis` widgets, `config` accepts: | Field name | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | string | A [BadgerQL query](/guides/insights/badgerql/) to execute. | | `vis.view` | string | The visualization view. One of `"table"`, `"line"`, `"bar"`, `"area"`, `"pie"`, `"billboard"`, `"histogram"`, `"scatter"`, or `"heatmap"`. | | `streams` | array | Optional list of stream slugs to query (for example `["default"]`). Defaults to all streams on the project. | ### Example with a widget [Section titled “Example with a widget”](#example-with-a-widget) ```bash curl -u AUTH_TOKEN: \ -X POST \ -H 'Content-type: application/json' \ -d '{ "dashboard": { "title": "Traffic overview", "widgets": [ { "type": "insights_vis", "grid": { "x": 0, "y": 0, "w": 12, "h": 3 }, "presentation": { "title": "Total requests" }, "config": { "query": "filter event_type::str == \"request\" | stats count() by bin()", "vis": { "view": "line" } } } ] } }' \ https://app.honeybadger.io/v2/projects/ID/dashboards ``` The request body is validated against the dashboard schema. A `422 Unprocessable Entity` response is returned when the payload violates the schema (unknown widget `type`, unknown properties, duplicate widget IDs, a title longer than 255 characters, etc.) or when the account’s dashboard or widget limit has been reached. See the [Insights dashboards guide](/guides/dashboards/) for more on the widget catalog and schema. In the Honeybadger UI, the **Edit Source** view exposes the full YAML-equivalent of the same schema used by this API. ## Update a dashboard [Section titled “Update a dashboard”](#update-a-dashboard) ```bash curl -u AUTH_TOKEN: \ -X PUT \ -H 'Content-type: application/json' \ -d '{"dashboard":{"title":"Updated title","widgets":[]}}' \ https://app.honeybadger.io/v2/projects/ID/dashboards/ID ``` Returns `204 No Content` on success. The request body uses the same fields as [Create a dashboard](#create-a-dashboard). The submitted `widgets` array replaces the existing one, so include every widget you want to keep. ## Delete a dashboard [Section titled “Delete a dashboard”](#delete-a-dashboard) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/dashboards/ID ``` Returns `204 No Content` on success. # Deployments API reference > API reference for managing deployments with endpoints to read and delete resources. ## Get a deploy list or deploy details [Section titled “Get a deploy list or deploy details”](#get-a-deploy-list-or-deploy-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/deploys curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/deploys/ID ``` Returns a list of deploys or a single deploy for the given project with the following format: ```json { "created_at": "2013-04-30T13:12:51Z", "environment": "production", "local_username": "deploy", "project_id": 1, "repository": "some/repo", "revision": "2013-04-29-take-2-16-g6cf7eae" } ``` The deploy list can be filtered with a number of URL parameters: | Parameter | Description | | ---------------- | --------------------------------------------------------- | | `environment` | A string with the desired environment, e.g., ‘production’ | | `local_username` | Username of the person doing the deployment | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `created_before` | A Unix timestamp (number of seconds since the epoch) | | `limit` | Number of results to return (max and default are 25) | The deploy list is always ordered by creation time descending. ## Delete a deploy [Section titled “Delete a deploy”](#delete-a-deploy) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/deploys/ID ``` # Environments API reference > API reference for managing environments with endpoints to retrieve and configure environment-specific settings. In Honeybadger, errors are grouped by the environment they occurred in. When an error is reported with a new environment, the environment is automatically stored, so you can search and filter by it in the future. You can also add, remove and manage your projects’ environments via the API. ## Get all environments [Section titled “Get all environments”](#get-all-environments) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/PROJECT_ID/environments ``` Returns a list of all recorded environments in this project. ```json { "results": [ { "id": 1, "project_id": 1, "name": "production", "notifications": true, "created_at": "2021-08-10T13:56:29.513358Z", "updated_at": "2021-08-10T13:56:29.513358Z" } ], "links": { "self": "http://localhost:3000/v2/projects/1/environments" } } ``` ## Get a single environment’s details [Section titled “Get a single environment’s details”](#get-a-single-environments-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/PROJECT_ID/environments/ID ``` ```json { "id": 1, "project_id": 1, "name": "production", "notifications": true, "created_at": "2021-08-10T13:56:29.513358Z", "updated_at": "2021-08-10T13:56:29.513358Z" } ``` ## Create an environment [Section titled “Create an environment”](#create-an-environment) ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \ -d '{ "environment": { "name": "Test", "notifications": true } }' https://app.honeybadger.io/v2/projects/PROJECT_ID/environments ``` You can specify these fields within the `environment` object: | Field name | Type | Description | | --------------- | ------- | ---------------------------------------------------------------------- | | `name` | string | The name of the environment | | `notifications` | boolean | (Optional) Enable notifications for this environment. Default: `true`. | Returns a 201 Created response containing the created environment’s details. ## Update an environment [Section titled “Update an environment”](#update-an-environment) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' \ -d '{ "environment": { "name": "Staging", "notifications": false } }' https://app.honeybadger.io/v2/projects/PROJECT_ID/environments/ID ``` You can specify any of these fields within the `environment` object: | Field name | Type | Description | | --------------- | ------- | ----------------------------------------- | | `name` | string | The name of the environment | | `notifications` | boolean | Enable notifications for this environment | Returns an empty response (204 No Content) if successful. ## Delete an environment [Section titled “Delete an environment”](#delete-an-environment) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/PROJECT_ID/environments/ID ``` Returns an empty response (204 No Content) if successful. # Errors API reference > API reference for managing errors (faults) with endpoints to create, read, update, and delete error data. ## Get a fault list or fault details [Section titled “Get a fault list or fault details”](#get-a-fault-list-or-fault-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID ``` Returns a list of faults or a single fault for the given project with the following format: ```json { "action": "runtime_error", "assignee": { "email": "westley@honeybadger.io", "id": 1, "name": "Westley" }, "comments_count": 0, "component": "pages", "created_at": "2013-01-22T16:33:22.704628Z", "environment": "development", "id": 2, "ignored": false, "klass": "RuntimeError", "last_notice_at": "2013-02-11T19:18:31.991903Z", "message": "This is a runtime error", "notices_count": 7, "project_id": 1, "resolve_on_deploy": false, "resolved": false, "tags": ["internal"], "url": "https://app.honeybadger.io/projects/1/faults/2" } ``` The fault list can be filtered with a number of URL parameters: | Parameter | Description | | ----------------- | ---------------------------------------------------- | | `q` | A [search string](/guides/errors/search/) | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `occurred_after` | A Unix timestamp (number of seconds since the epoch) | | `occurred_before` | A Unix timestamp (number of seconds since the epoch) | | `limit` | Number of results to return (max and default are 25) | The fault list can be ordered with the order parameter in the URL, with the following possible values: | Value | Description | | ---------- | --------------------------------------------------------------- | | `recent` | List the errors that have most recently occurred first | | `frequent` | List the errors that have received the most notifications first | The default order is by creation time. If the search query affects the amount of matched notices, the `notices_count` field may not be accurate. For those cases, we add a `notices_count_in_range` field to the payload which reflects the notice counts with the query applied. ## Get a count of faults [Section titled “Get a count of faults”](#get-a-count-of-faults) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/summary ``` Returns a total count of all the errors for a project and counts of errors grouped by environment, resolution status, and ignored status. The counts can be filtered by these parameters: | Parameter | Description | | ----------------- | ---------------------------------------------------- | | `q` | A [search string](/guides/errors/search/) | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `occurred_after` | A Unix timestamp (number of seconds since the epoch) | | `occurred_before` | A Unix timestamp (number of seconds since the epoch) | For example, to get a count of open faults in production, you would use the `q` parameter to filter the results: ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/summary?q=environment%3Aproduction%20-is%3Aresolved%20-is%3Aignored ``` ## Update a fault [Section titled “Update a fault”](#update-a-fault) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"fault":{"resolved":true}}' https://app.honeybadger.io/v2/projects/ID/faults/ID ``` The following fields can be updated: | Field name | Type | Description | | ------------------- | ------- | ---------------------------------------------------------- | | `resolved` | boolean | | | `ignored` | boolean | | | `assignee_id` | integer | | | `resolve_on_deploy` | boolean | Mark the fault to be resolved automatically on next deploy | Setting `resolved` or `ignored` to `true` in the same request takes precedence over `resolve_on_deploy`: the fault is resolved or ignored immediately and is not left marked for deploy. The current `resolve_on_deploy` state is also returned on each fault (see the fault details above). ## Delete a fault [Section titled “Delete a fault”](#delete-a-fault) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/faults/ID ``` ## Get a count of occurrences for a fault [Section titled “Get a count of occurrences for a fault”](#get-a-count-of-occurrences-for-a-fault) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/occurrences ``` Provides the number of times errors have been encountered for a particular fault. ```json [ [ 1510963200, 1 ], [ 1511049600, 0 ], [ 1511136000, 0 ], [ 1511222400, 1 ], ... ] ``` The data can be filtered with these URL parameters: | Parameter | Description | | --------- | ------------------------------------------------------------ | | `period` | One of “hour”, “day”, “week”, or “month”. Defaults to “hour” | ## Pausing and unpausing faults [Section titled “Pausing and unpausing faults”](#pausing-and-unpausing-faults) You can pause notifications for a period of time or for the number of occurrences of a fault. This doesn’t affect the resolved/unresolved status. If a fault is resolved while paused, new occurrences will still mark it as unresolved — you just won’t be notified about it. For time-based pauses, notifications resume on the first occurrence received after the time period has elapsed. For count-based pauses, notifications resume on the occurrence that exhausts the count. In both cases, a notification will be sent even if the fault was already reopened by an earlier occurrence during the pause. ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"time":"day"}' https://app.honeybadger.io/v2/projects/ID/faults/ID/pause curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"count":100}' https://app.honeybadger.io/v2/projects/ID/faults/ID/pause ``` Valid values for `time` are “hour”, “day”, and “week”, and valid values for `count` are 10, 100, and 1000. You can clear the pause for a fault, or for all of a project’s faults: ```bash curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/unpause curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/unpause ``` You don’t need to provide a request body for the unpause endpoints. The response body will be empty, and the status code will be 200. ## Bulk-resolving faults [Section titled “Bulk-resolving faults”](#bulk-resolving-faults) You can mark all faults for a project as resolved using this endpoint: ```bash curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/resolve ``` The faults to be resolved can be filtered with the URL parameter `q`, which is a [search string](/guides/errors/search/). Faults that are already resolved are skipped. On success the response body is empty. The status code tells you whether the update was completed or was queued: | Status | Meaning | | ------ | -------------------------------------------------------------------------------- | | 200 | Up to 1,000 faults matched. They were all resolved before the response was sent. | | 202 | More than 1,000 faults matched. The work was queued and runs in the background. | If the background work can’t be queued, the endpoint returns a 500 with an `errors` field, and nothing is resolved. Retry the request in that case. ## Linking faults to existing 3rd-party issues [Section titled “Linking faults to existing 3rd-party issues”](#linking-faults-to-existing-3rd-party-issues) ```bash curl -u AUTH_TOKEN: -H 'Content-type: application/json' -d '{"channel_id":123, "data":{"number":42}}' -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/link ``` This associates an existing GitHub issue, Pivotal Tracker story, etc. with a fault. Once associated, the error detail page in the UI will include a link to the associated issue. The `channel_id` portion of the payload can be obtained from the [integrations](/api/projects#get-a-list-of-integrations-for-a-project) API endpoint. The `data` portion of the payload varies depending on which type of integration is being referenced: ### GitHub [Section titled “GitHub”](#github) | Field name | type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------- | | `number` | integer | The issue number at the end of the issue URL: \*\* | ### Jira [Section titled “Jira”](#jira) | Field name | type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------- | | `id` | integer | The issue id at the end of the issue URL: \*\* | | `key` | string | The issue label: HB-123 | | `self` | url | The issue URL: | ### Pivotal Tracker [Section titled “Pivotal Tracker”](#pivotal-tracker) | Field name | type | Description | | ------------- | ------- | -------------------------------------------------------------------------------------------------- | | `story_id` | integer | The story number at the end of the story URL: \*\* | | `project_id` | integer | The Pivotal Tracker project ID | | `pivotal_url` | url | The story URL: | ### Trello [Section titled “Trello”](#trello) | Field name | type | Description | | ---------- | ------ | ------------------------------------------------------------------ | | `id` | string | The card ID, e.g. 60ca3275a482444bcaae2a8a | | `shortUrl` | url | Shortened version of the card URL: | This endpoint is also used to update an existing link (e.g., to change the issue number for a linked GitHub issue). ## Unlinking faults [Section titled “Unlinking faults”](#unlinking-faults) ```bash curl -u AUTH_TOKEN: -H 'Content-type: application/json' -d '{"channel_id":123}' -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/unlink ``` This removes the link to an associated GitHub issue, Pivotal Tracker story, etc. The `channel_id` portion of the payload can be obtained from the [integrations](/api/projects/#get-a-list-of-integrations-for-a-project) API endpoint. ## Get a list of notices [Section titled “Get a list of notices”](#get-a-list-of-notices) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/notices ``` Returns a list of notices for the given fault with the following format: ```json { "created_at": "2013-02-11T19:18:31.123931Z", "environment": { "environment_name": "development", "hostname": "apollo.local", "project_root": { "path": "/Users/bob/code/crywolf" } }, "cookies" { ... }, "fault_id": 2, "id": "f78391e4-7789-49f0-888e-5f6c07a222f2", "url": "https://app.honeybadger.io/projects/1/faults/2/d23e5f62-747f-11e2-a65e-4f2716edc8b7" "message": "RuntimeError: This is a runtime error", "web_environment": { "CONTENT_LENGTH": "82", "CONTENT_TYPE": "application/x-www-form-urlencoded", "HTTP_USER_AGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/537.4 (KHTML, like Gecko) Chrome/22.0.1229.79 Safari/537.4", ... }, "request": { "action": "runtime_error", "component": "pages", "context": { "cart_id": "8EF99AFC-B4DB-4FC5-A92A-9A6F86ABD364" }, "params": { "_method": "post", "a": "1", "action": "runtime_error", "authenticity_token": "...", "b": "2", "controller": "pages" }, "session": { "_csrf_token": "...", "session_id": "..." }, "url": "http://example.com/pages/runtime_error?a=1&b=2", "user": { "email": "foo@bar.com", "id": 1 } }, "backtrace": [ { "number": "4", "file": "/Users/westley/code/crywolf/app/controllers/pages_controller.rb", "method": "runtime_error" }, ... ], "application_trace": [] } ``` The notice list can be filtered with these URL parameters: | Parameter | Description | | ---------------- | ---------------------------------------------------- | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `created_before` | A Unix timestamp (number of seconds since the epoch) | | `limit` | Number of results to return (max and default are 25) | The notice list is always ordered by creation time descending. ## Get a list of affected users [Section titled “Get a list of affected users”](#get-a-list-of-affected-users) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/affected_users ``` Returns a list of the users who were affected by an error: ```json [ { "user": "bob@example.com", "count": 4 }, { "user": "ann@example.com", "count": 1 } ] ``` The data can be filtered with the URL parameter `q`, which is a [search string](/guides/errors/search/). # Data API > Get started with Honeybadger's REST API including authentication, rate limits, and basic usage examples. Our REST Data API can be used to access the data stored in your Honeybadger account and to make changes to your account data. To learn about reporting exception data, deployments, and other events, check out the [API](/api/) documentation. ## Glossary [Section titled “Glossary”](#glossary) The resource names used by the API may be different from those used in our web UI. Here is a glossary of the most important resource names: * **Project:** A container that holds all your data for a single app or service. * **Fault:** Called an “error” in the web UI. It has many Notices. * **Notice:** Called an “error occurrence” in the web UI. * **Site:** Called an “uptime check” in the web UI. * **CheckIn:** Manages dead-man-switch checks. * **Team:** Connects Honeybadger users to projects. * **TeamInvitation:** Invites a user to join a team. ## Authentication [Section titled “Authentication”](#authentication) Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Each request should be sent with your personal authentication token (available from [your profile page](https://app.honeybadger.io/users/edit)) as the basic auth username value. You do not need to provide a password. For example, you can request your projects list with `curl` like so (the trailing colon after the token prevents curl from asking for a password): ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects ``` ## Rate limiting [Section titled “Rate limiting”](#rate-limiting) You can make up to 360 requests per hour to our API. After you reach the limit for the hour, additional requests will receive a response with the 403 (Forbidden) status code. The following headers, returned with every API response, can provide you the information about your rate limit: | Header | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | | `X-RateLimit-Limit` | The number of requests that you can make per hour | | `X-RateLimit-Remaining` | The number of requests you can make before getting an error | | `X-RateLimit-Reset` | A Unix timestamp (number of seconds since the epoch) when remaining requests counter will be reset to the maximum | ## Format [Section titled “Format”](#format) The API returns JSON by default, but you should include `Accept: application/json` in your request headers. Lists of items are always paginated, even if there is only one page of results. The general response format for a list is as follows: ```json { "links": { "self": "https://app.honeybadger.io/v2/...", "next": "https://app.honeybadger.io/v2/..." } "results": [ { ... }, { ... } ] } ``` You can get the page after the current page by loading the value found in the `next` element of the `links` hash and the page before the current page by loading the value found in the `prev` element of the links hash. Either or both of those elements may be missing from the links hash if we can determine there is no next page or previous page of results. On the other hand, there may be a next link that, when loaded, results in no records being found — in which case, the `results` top-level element will be an empty array. ## Requests and responses [Section titled “Requests and responses”](#requests-and-responses) When you create or update resources, send the request (via POST for creations or PUT for updates) with the `Content-type` header as application/json, the `Accept` header as application/json and the request body as a valid json object. No request body is required for deleting a resource via the DELETE method. A successful POST request will return a 201 status code and the JSON representation of the just-created resource as the response body. A PUT request that successfully updates an object will return a 204 status code with no response body. Responses for successful DELETE requests return a status code of 204 and an empty response body. Requests that result in errors will return a JSON response body like so: ```json { "errors": "Reason for error" } ``` The status code will be 403 if there is a permissions problem, 422 if the request was invalid, or in the 500 range if something unexpected happened. # Insights API reference > API reference for querying data with Insights. ## Query Insights data [Section titled “Query Insights data”](#query-insights-data) This endpoint executes a BadgerQL query against your project’s Insights data and returns the results. ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"query":"fields @ts, @preview | limit 3"}' https://app.honeybadger.io/v2/projects/ID/insights/queries ``` The following fields can be provided in the request body: | Field name | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | string | A [BadgerQL query string](/guides/insights/badgerql/) to execute against your Insights data | | `ts` | string | Optional timestamp range (defaults to `PT3H`). Accepts shortcuts (`today`, `week`) or ISO 8601 formats: durations (`P8D`), datetimes (`2021-12-14T22:14:08`), time intervals (`2021-12-10T00:00/2021-12-12T00:00`), or duration intervals (`P1W/P0D`). | | `timezone` | string | Optional timezone for timestamp interpretation. Must be a valid IANA timezone identifier (e.g., `America/New_York`, `UTC`, `Europe/London`). | | `stream_ids` | array | Optional list of [Insights stream IDs](/api/streams/) to query. Defaults to all streams on the project. IDs that don’t belong to the project are ignored. | Returns the query results with the following format: ```json { "results": [ { "@ts": "2025-11-18 11:40:05.802", "@preview": "{\"ctx.class\":\"UptimeWorker\",\"ctx.elapsed\":0.297,\"ctx.jid\":\"aed85cd96b60c142b8c9b835\",\"lvl\":\"INFO\",\"msg\":\"done\",\"pid\":1,\"tid\":\"1knd\"}" }, { "@ts": "2025-11-18 11:40:05.812", "@preview": "{\"ctx.class\":\"UptimeWorker\",\"ctx.elapsed\":0.198,\"ctx.jid\":\"dfb0be7609bb3d4747efb5fd\",\"lvl\":\"INFO\",\"msg\":\"done\",\"pid\":1,\"tid\":\"1kp5\"}" }, { "@ts": "2025-11-18 11:40:05.813", "@preview": "{\"ctx.class\":\"FaultMetricWorker\",\"ctx.elapsed\":0.22,\"ctx.jid\":\"f1f3b3a9b9d874ba82e97590\",\"lvl\":\"INFO\",\"msg\":\"done\",\"pid\":1,\"tid\":\"1ksp\"}" } ], "meta": { "query": "fields @ts, @preview | limit 3", "fields": [ "@ts", "@preview" ], "schema": [ { "name": "@ts", "type": "datetime" }, { "name": "@preview", "type": "json" } ], "row_count": 3, "total_count": 3, "start_at": "2025-11-18 11:11:26", "end_at": "2025-11-18 14:11:26" } } ``` The response includes: | Field name | Type | Description | | ------------------ | ------ | ------------------------------------------------- | | `results` | array | Array of objects containing the query results | | `meta.query` | string | The query that was executed | | `meta.fields` | array | List of fields included in the results | | `meta.schema` | array | Schema information for each field (name and type) | | `meta.row_count` | number | Number of rows returned in this response | | `meta.total_count` | number | Total number of rows matching the query | | `meta.start_at` | string | Start of the time range for the query | | `meta.end_at` | string | End of the time range for the query | Please see the [BadgerQL guide](/guides/insights/badgerql/) for the query syntax to use for the `query` field. # Projects API reference > API reference for managing projects with endpoints to create, retrieve, update, and delete resources, and fetch reports. ## Get a project list or project details [Section titled “Get a project list or project details”](#get-a-project-list-or-project-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects?account_id=ACCOUNT_ID curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID ``` Returns a list or a single project with the following format: ```json { "active": true, "created_at": "2012-06-09T20:33:27.798800Z", "disable_public_links": false, "earliest_notice_at": "2015-12-18T19:30:32.470689Z", "environments": ["development", "production"], "fault_count": 14, "id": 1, "last_notice_at": "2016-06-14T18:31:54.000000Z", "name": "Rails exception tracking gem", "owner": { "email": "westley@honeybadger.io", "id": 1, "name": "Westley" }, "purge_days": 30, "resolve_errors_on_deploy": true, "sites": [ { "active": true, "id": "9eed6a7e-af77-4cc6-8c55-7a5afa59a90b", "last_checked_at": "2016-06-15T12:57:29.646956Z", "name": "Main site", "state": "up", "url": "http://www.example.com" } ], "streams": [ { "id": "a1b2c3d4e5f6", "name": "Default", "slug": "default", "internal": false, "project_id": 1, "created_at": "2026-07-15T13:56:29.513358Z" }, { "id": "f6e5d4c3b2a1", "name": "Internal", "slug": "internal", "internal": true, "project_id": 1, "created_at": "2026-07-15T13:56:29.513358Z" } ], "teams": [ { "id": 1, "name": "Team Marie" } ], "token": "098sflj2", "unresolved_fault_count": 1, "users": [ { "email": "inigo@honeybadger.io", "id": 2, "name": "Inigo Montoya" }, { "email": "westley@honeybadger.io", "id": 1, "name": "Westley" } ] } ``` If the `account_id` parameter is not supplied when requesting the list of projects, all projects will be returned across all accounts to which the provided AUTH\_TOKEN has access. `purge_days` is `null` when the project has no explicit retention setting of its own, in which case data is retained for the maximum number of days available to your subscription plan. ## Create a project [Section titled “Create a project”](#create-a-project) ```bash curl -u AUTH_TOKEN: \ -X POST \ -H 'Content-type: application/json' \ -d '{"project":{"name":"My project"}}' \ https://app.honeybadger.io/v2/projects?account_id=ACCOUNT_ID ``` Here is a list of the fields that can be provided: | Field name | Type | Description | | -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | | | `resolve_errors_on_deploy` | boolean | Whether all unresolved faults should be marked as resolved when a deploy is recorded | | `disable_public_links` | boolean | Whether to allow fault details to be publicly shareable via a button on the fault detail page | | `language` | string | One of “js”, “elixir”, “golang”, “java”, “node”, “php”, “python”, “ruby”, or “other” | | `user_url` | string | A URL format like `"http://example.com/admin/users/[user_id]"` that will be displayed on the fault detail page and have \[user\_id] replaced with the user\_id from the fault’s context hash. | | `source_url` | string | A URL format like `"https://gitlab.com/username/reponame/blob/[sha]/[file]#L[line]"` that is used to link lines in the backtrace to your git browser. This can be left blank if you provide the repository info in your deploy payloads or if you use the GitHub integration for your project. | | `purge_days` | integer | The number of days to retain data (up to the max number of days available to your subscription plan). | | `user_search_field` | string | A field such as “context.user\_email” that you provide in your error context. This field will be used to create the aggregated list of affected users. | If the `account_id` query parameter is not provided, the project will be associated with the first account accessible by the user associated with the AUTH\_TOKEN. ## Update a project [Section titled “Update a project”](#update-a-project) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"project":{"name":"Updated project name"}}' https://app.honeybadger.io/v2/projects/ID ``` The fields listed in the prior section are also available when updating a project. ## Delete a project [Section titled “Delete a project”](#delete-a-project) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID ``` ## Get a count of occurrences for all projects or a single project [Section titled “Get a count of occurrences for all projects or a single project”](#get-a-count-of-occurrences-for-all-projects-or-a-single-project) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/occurrences curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/occurrences ``` Provides the number of times errors have been encountered in your project or across all your projects. ```json [ [ 1510963200, 1440 ], [ 1511049600, 1441 ], [ 1511136000, 1441 ], [ 1511222400, 1441 ], ... ] ``` The data is returned as an array of epoch seconds/count pairs, and it can be filtered with these URL parameters: | Parameter | Description | | ------------- | ------------------------------------------------------------ | | `period` | One of “hour”, “day”, “week”, or “month”. Defaults to “hour” | | `environment` | Limit results to this environment | When the period is “hour” (the default), the data returned is the most recent 60 one-minute buckets. When it is “day”, the data comes from the most recent 24 one-hour buckets, and when it is “week” or “month”, the data is grouped into one-day buckets. All times and bucket boundaries are UTC. ## Get a list of integrations for a project [Section titled “Get a list of integrations for a project”](#get-a-list-of-integrations-for-a-project) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/integrations ``` Returns a list of integrations (a.k.a. channels) for a project: ```json [ { "id": 9693, "active": false, "events": ["occurred", "assigned"], "site_ids": ["605e7c8e-e6c8-4102-a8f8-37a9431ee78be"], "options": { "url": "http://requestb.in/7d87eae" }, "excluded_environments": [], "filters": [], "type": "WebHook" } ] ``` The `options` element varies depending on the type of integration. ## Get report data [Section titled “Get report data”](#get-report-data) The following endpoints provide the data that is displayed on the Reports tab for a project. These URL parameters can be used to filter the data returned by each of the report endpoints: | Parameter | Description | | ------------- | ---------------------------------------------------------------------- | | `start` | Date/time in ISO 8601 format for the beginning of the reporting period | | `stop` | Date/time in ISO 8601 format for the end of the reporting period | | `environment` | Limit results to this environment | ### Notices by class [Section titled “Notices by class”](#notices-by-class) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/reports/notices_by_class ``` Returns a count of error notifications processed, grouped by class. ```json [ ["RuntimeError", 8347], ["SocketError", 4651] ] ``` ### Notices by location [Section titled “Notices by location”](#notices-by-location) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/reports/notices_by_location ``` Returns a count of error notifications processed, grouped by location. The location is framework-dependent; e.g., for Rails applications it’s a combination of the controller and the action. ```json [ ["inquiries#create", 2904], ["members#details", 862] ] ``` ### Notices by user [Section titled “Notices by user”](#notices-by-user) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/reports/notices_by_user ``` Returns a count of error notifications processed, grouped by user (assuming you are providing user\_id and/or user\_email in the context). ```json [ ["julia@example.com", 579], ["marie@example.com", 289] ] ``` ### Notices by day [Section titled “Notices by day”](#notices-by-day) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/reports/notices_per_day ``` Returns a count of error notifications processed, grouped by day (with days starting at midnight UTC). ```json [ ["2023-01-24T00:00:00.000000+00:00", 3161], ["2023-01-25T00:00:00.000000+00:00", 2620], ["2023-01-26T00:00:00.000000+00:00", 2852], ["2023-01-27T00:00:00.000000+00:00", 2502], ["2023-01-28T00:00:00.000000+00:00", 1759], ["2023-01-29T00:00:00.000000+00:00", 1420], ["2023-01-30T00:00:00.000000+00:00", 3027], ["2023-01-31T00:00:00.000000+00:00", 1624] ] ``` # Reporting check-ins > API reference for reporting check-ins to Honeybadger to monitor scheduled tasks and cron jobs. To report a check-in, simply send a GET request to the endpoint URL you received when creating the check-in: ```bash curl https://api.honeybadger.io/v1/check_in/XyZZy ``` You can also send an email (no subject or body required) to `XyZZy@report.hbchk.in`, where `XyZZy` is the same (case-sensitive) ID from the endpoint URL. If you specify a [slug](/guides/check-ins/#slugs) for a check-in, you can use that slug and the project’s API key in the URL rather than the ID: ```bash curl https://api.honeybadger.io/v1/check_in/PROJECT_API_KEY/my_identifier ``` ## Check-in payloads [Section titled “Check-in payloads”](#check-in-payloads) Business-tier accounts can send additional check-in details via POST. The payload is optional and must be under 20KB. ```bash curl -X POST https://api.honeybadger.io/v1/check_in/XyZZy \ -H "Content-Type: application/json" \ -d '{ "check_in": { "status": "success", "duration": 1234, "stdout": "backup completed", "stderr": "", "exit_code": 0 } }' ``` The `check_in` object supports: * `status` (string): `success` or `error` * `duration` (integer): milliseconds * `stdout` (string): captured standard output * `stderr` (string): captured standard error * `exit_code` (integer): process exit code The data sent with the `check_in` object will be sent to [Insights](/guides/insights/) as part of the check-in event. You can find more information on using check-ins [here](/guides/check-ins/). # Reporting deployments > API reference for reporting deployments to Honeybadger. Use this endpoint to notify Honeybadger when a deploy occurs. For an overview of all reporting methods, see the [Deployments guide](/guides/deployments/#reporting-deployments). ## POST /v1/deploys [Section titled “POST /v1/deploys”](#post-v1deploys) Make a POST request to `https://api.honeybadger.io/v1/deploys` with the following parameters: | Parameter | Required | Description | | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- | | api\_key | Required | Your project’s API key | | deploy\[environment] | Optional | The environment name. Example: `production` | | deploy\[revision] | Optional | The VCS revision being deployed. Could be a git hash, or a tag name. Example: `7cd4bac1bd7e2ddf858d10ee86e362c8d8e2f912` | | deploy\[repository] | Optional | The base URL of the VCS repository. It should be HTTPS-style. Example: `https://github.com/honeybadger-io/honeybadger-ruby` | | deploy\[local\_username] | Optional | The name of the user who is deploying. Example: `Jane` | Example `curl` command: ```sh HONEYBADGER_ENV="production" \ HONEYBADGER_REVISION="$(git rev-parse HEAD)" \ HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \ HONEYBADGER_API_KEY="Your project API key" \ && curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY" ``` You can also send a JSON payload with `Content-Type: application/json`: ```bash curl https://api.honeybadger.io/v1/deploys \ -H 'X-API-Key: Your project API key' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "deploy": { "environment": "production", "local_username": "sam", "revision": "7cd4bac1bd7e2ddf858d10ee86e362c8d8e2f912", "repository": "https://github.com/someuser/somerepo" } }' ``` A successful response returns `{"status":"OK"}`. # Reporting events > API reference for sending events to Honeybadger Insights for monitoring and analysis. Events you send to this API will appear in [Honeybadger Insights](/guides/insights), where you can query and visualize the events. Your [newline-delimited JSON](https://en.wikipedia.org/wiki/JSON_streaming#Newline-Delimited_JSON) payload should be submitted as the body of a POST request to with the following headers: * X-API-Key: The API key from your project settings page * Accept: application/json * User-Agent: ”{{ Client name }} {{ client version }}; {{ language version }}; {{ platform }}” Regarding the format of the User-Agent header, you can see an example of how that’s generated in our Ruby implementation [here](https://github.com/honeybadger-io/honeybadger-ruby/blob/991d7cb85ea3f224d6cf0943a87f690de9f9b051/lib/honeybadger/util/http.rb#L21), which generates a string like this: `HB-Ruby 2.1.1; 2.2.7; x86_64-linux-gnu`. If you don’t have all this information available to send, that’s OK, but the more the merrier. :) If all went well with your POST, you’ll get a response with the status code 201 and information about the just-logged error as a JSON hash. If all *didn’t* go well, you could get a response with one of these status codes: | Status Code | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `403` | Either the API key is incorrect or the account has been deactivated | | `413` | The payload size was too large. The maximum acceptable size is 102,400 bytes | | `422` | The payload couldn’t be processed. | | `429` | The API key was valid, but the payload was not accepted because you hit a rate limit (i.e., we have received too much traffic for this API key). | | `500` | Our bad! :) | ## Sample payloads [Section titled “Sample payloads”](#sample-payloads) Each line of the payload must be a single JSON object. The structure of the events you send to this endpoint is up to you, based on your use case. For example, if you wanted to send lines from an unstructured log, you could send a payload like this: ```json {"ts": "2023-08-31T09:19:30Z", "message": "This is a log line"} {"ts": "2023-08-31T09:19:30Z", "message": "This is another log line"} ``` We strongly recommend you send structured logs to make querying a better experience: ```json { "ts": "2023-08-31T16:17:57Z", "level": "info", "action": "health", "controller": "PagesController", "method": "GET", "path": "/health", "status": 200, "duration": 322 } ``` Sending events in this way would make it easy to do analytical queries like average request duration, counts by request path, etc. Of course, you aren’t limited to logs — you can track any kind of event that makes sense for your application: ```json {"ts": "2023-08-31T14:31:05Z", "event": "user.signup", "user": {"id": 42, "source": "Daring Fireball Ad"}} {"ts": "2023-08-31T14:33:05Z", "event": "company.created", "project": {"id": 54, "name": "Spacely Space Sprockets", "shared": true}} ``` You do not need to include a `ts` element in each JSON object, but if you do, it must be an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339)-formatted timestamp. If `ts` is omitted, or if it can’t be parsed as a timestamp, it will be added or replaced with the value of the current time as of the payload being processed. ## Setting default fields with a query parameter [Section titled “Setting default fields with a query parameter”](#setting-default-fields-with-a-query-parameter) You can pass a `defaults` query parameter containing a URL-encoded JSON object, and its fields will be merged into every event in the batch: ```plaintext POST https://api.honeybadger.io/v1/events?defaults={"environment":"production","region":"us-east-1"} ``` With that parameter, this payload: ```json {"message": "This is a log line"} {"message": "This is another log line", "environment": "staging"} ``` …is stored as: ```json {"message": "This is a log line", "environment": "production", "region": "us-east-1"} {"message": "This is another log line", "environment": "staging", "region": "us-east-1"} ``` Fields already present in an event always win — a default never overwrites data you send in the payload. The `defaults` parameter has a few restrictions: * It must be a flat JSON object; values must be strings, numbers, or booleans. * The keys `event_type` and `ts` are reserved and will be ignored. * It’s limited to 16 keys and 2kB (URL-decoded). * The 100kB per-event size limit applies to events after defaults are merged. An invalid `defaults` parameter never causes the request to fail: entries that break the rules above are dropped (an unparseable or oversized parameter is ignored entirely), and the events are ingested as sent. ## Sending events from log files and other sources [Section titled “Sending events from log files and other sources”](#sending-events-from-log-files-and-other-sources) Check out our instructions on how to add data from other sources, like your log files, Heroku apps, etc., in our [Insights Guide](/guides/insights#adding-data-from-other-sources). ## Limits [Section titled “Limits”](#limits) Nested JSON structures are supported, but limiting the nesting to 2 or 3 levels is best. Each event must be less than 100kB, and the total request size must be less than 5MB. Information about the quotas for this endpoint can be found [here](/resources/quotas/#insights). # Reporting errors > API reference for reporting exceptions to Honeybadger with request formats, parameters, and response structures. Your JSON payload should be submitted as the body of a POST request to , with the following headers: * X-API-Key: The API key from your project settings page * Content-Type: application/json * Accept: application/json * User-Agent: ”{{ Client name }} {{ client version }}; {{ language version }}; {{ platform }}” Regarding the format of the User-Agent header, you can see an example of how that’s generated in our Ruby implementation [here](https://github.com/honeybadger-io/honeybadger-ruby/blob/991d7cb85ea3f224d6cf0943a87f690de9f9b051/lib/honeybadger/util/http.rb#L21), which generates a string like this: `HB-Ruby 2.1.1; 2.2.7; x86_64-linux-gnu`. If you don’t have all this information available to send, that’s OK, but the more the merrier. :) If all went well with your POST, you’ll get a response with the status code 201 and information about the just-logged error as a JSON hash: ```json { "id": "6840eec9-6903-4f13-b511-b91ee46fda6a" } ``` You can use that ID to jump directly to the error in our UI: E.g., `https://app.honeybadger.io/notice/6840eec9-6903-4f13-b511-b91ee46fda6a` If all *didn’t* go well, you could get a response with one of these status codes: | Status Code | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `403` | Either the API key is incorrect or the account has been deactivated | | `413` | The payload size was too large. The maximum acceptable size is 262,144 bytes (256KB) | | `422` | The payload couldn’t be processed. Please note that we only do *minimal* checking of the payload when it hits our API. It’s entirely possible to get a 201 response, only to have the payload end up not being able to processed later in the pipeline and thus not show up in the UI. | | `429` | The API key was valid, but the payload was not accepted because you hit a rate limit (i.e., we have received too much traffic for this API key). | | `500` | Our bad! :) | ## Sample payload [Section titled “Sample payload”](#sample-payload) Your JSON will probably vary most from the example in the `request` key of the hash, which supplies info about the request made by the user, the web server environment, and so on. The `context` key of the `request` hash should have information about the logged-in user, if any, so that we can report on the users effected by application errors. The `backtrace` key of the `error` hash is essential, as that is used for grouping similar errors together in the Honeybadger UI. The `class` and `message` keys of the `error` hash are displayed in the Honeybadger UI and used for posting errors to other services, like Github issues. Here’s an annotated payload for your enjoyment: ```json { // Please use relevant values for the name, url, and version keys of the // `notifier` key that point back to your code/package. "notifier": { "name": "Honeybadger Notifier", "url": "https://github.com/honeybadger-io/honeybadger-ruby", "version": "1.0.0" }, // Here's where your exception's class, message tags and backtrace go. // The `class` and `message` attributes are what make up the error's "title" that we display in the UI. // The `fingerprint` attribute is an optional string that is used to force errors with the same fingerprint (regardless of error class, message, or location) to be grouped together. // The `backtrace` is a ruby-style backtrace. If the `source` attribute is included for a backtrace line, it will be displayed as a snippet in the UI, // Last but not least, `causes` is an optional list of causes for the error. // Honeybadger displays causes in the order they are listed here. "error": { "class": "RuntimeError", "message": "RuntimeError: This is a runtime error, generated by the crywolf app", "tags": ["wubba"], "fingerprint": "optional string to force errors with the same fingerprint to be grouped together", "backtrace": [ { "number": "4", "file": "/crywolf/app/controllers/pages_controller.rb", "method": "runtime_error", "source": { "2": "", "3": " def runtime_error", "4": " raise RuntimeError.new(\"This is a runtime error, generated by the crywolf app\")", "5": " end", "6": "" } }, { "number": "4", "file": "/gems/1.9.3-p194/lib/ruby/gems/1.9.1/gems/actionpack-3.2.8/lib/action_controller/metal/implicit_render.rb", "method": "send_action" } ], "causes": [ { "class": "StandardError", "message": "StandardError: This is the first cause", "backtrace": [ { "number": "8", "file": "/crywolf/app/models/page.rb", "method": "find" }, { "number": "13", "file": "/crywolf/app/services/find.rb", "method": "call" } ] } ] }, // `breadcrumbs` are any interesting events that happened within the request leading up to the error "breadcrumbs": { "enabled": true, "trail": [ { "category": "query", "message": "Active Record", "metadata": { "sql": "SELECT ?.? FROM ? ORDER BY ?.? ASC", "connection_id": 14200, "duration": 0.0001449 }, "timestamp": "2021-03-11T23:08:45.448Z" }, { "category": "request", "message": "Action Controller Start Process", "metadata": { "controller": "PagesController", "action": "home", "format": "html", "method": "GET", "path": "/pages/home", "duration": 0.0000136 }, "timestamp": "2021-03-11T23:08:45.451Z" }, { "category": "render", "message": "Action View Template Render", "metadata": { "identifier": "/usr/lib/ruby/gems/2.7.0/gems/actionpack-6.0.3.5/lib/action_dispatch/middleware/templates/rescues/ diagnostics.html.erb", "layout": "rescues/layout", "duration": 0.0092867 }, "timestamp": "2021-03-11T23:08:45.554Z" }, { "category": "error", "message": "RuntimeError", "metadata": { "exception_message": "This is a runtime error, generated by the crywolf app" }, "timestamp": "2021-03-11T23:08:45.555Z" }, { "category": "notice", "message": "Honeybadger Notice", "metadata": { "exception": "This is a runtime error, generated by the crywolf app" }, "timestamp": "2021-03-11T23:08:45.555Z" } ] }, // `request` contains information about the HTTP request that caused this exception. "request": { // We display this data on the error's details page. // `user_id` and `user_email` are special keys that are used to generate the "affected users" list in the UI. "context": { "user_id": 123, "user_email": "test@example.com" }, // In rails this is the Controller. "component": "pages", // In rails this is the Action. "action": "runtime_error", // The URL where the error occurred "url": "http://crywolf.dev/pages/runtime_error?a=1&b=2", // These are displayed under "params" on the error detail page "params": { "_method": "post", "authenticity_token": "tuZ7y1PUEMadgKevSzgSUK6T0p267I1+NL0+rnR7xrI=", "a": "1", "b": "2", "controller": "pages", "action": "runtime_error" }, // These are displayed under "session" on the error detail page "session": { "session_id": "57fb796258046e92b3201ece44531320", "_csrf_token": "tuZ7y1PUEMadgKevSzgSUK6T0p267I1+NL0+rnR7xrI=" }, // These are displayed under "web environment" on the error detail page. // Normally you'll just include the environment variables set by your web server. "cgi_data": { "REQUEST_METHOD": "POST", "PATH_INFO": "/pages/runtime_error", "QUERY_STRING": "a=1&b=2", "SCRIPT_NAME": "", "REMOTE_ADDR": "127.0.0.1", "SERVER_ADDR": "0.0.0.0", "SERVER_NAME": "crywolf.dev", "SERVER_PORT": "80", "HTTP_HOST": "crywolf.dev", "HTTP_CONNECTION": "keep-alive", "CONTENT_LENGTH": "82", "HTTP_CACHE_CONTROL": "max-age=0", "HTTP_ORIGIN": "http://crywolf.dev", "HTTP_USER_AGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/537.4", "CONTENT_TYPE": "application/x-www-form-urlencoded", "HTTP_ACCEPT": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "HTTP_REFERER": "http://crywolf.dev/", "HTTP_ACCEPT_ENCODING": "gzip,deflate,sdch", "HTTP_ACCEPT_LANGUAGE": "en-US,en;q=0.8", "HTTP_ACCEPT_CHARSET": "ISO-8859-1,utf-8;q=0.7,*;q=0.3", "HTTP_COOKIE": "_crywolf_session=BAh7B0kiD3Nlc3Npb25faWQGOgZFRkkiJTU3ZmI3OTYy", "REMOTE_PORT": "52509", "ORIGINAL_FULLPATH": "/pages/runtime_error?a=1&b=2" } }, "server": { // The directory where your code lives. This helps us to display more concise paths. "project_root": "/Users/josh/code/crywolf", // Your environment name "environment_name": "development", // The server's hostname "hostname": "Josh-MacBook-Air.local", // Optional: Git sha for the deployed version of the code, for linking to GitHub, Gitlab, and BitBucket "revision": "920201a", // Optional: ID of the process that raised the error "pid": 1138 } } ``` ## Payload tester [Section titled “Payload tester”](#payload-tester) While you’re developing an error collector in your language of choice that talks to our API, you can use our [payload tester](https://app.honeybadger.io/notice/test) to see how your payloads will be rendered in our UI. # Uploading source maps > API reference for uploading source maps to Honeybadger to get readable stack traces from minified JavaScript code. Honeybadger can automatically un-minify your JavaScript code if you provide a [source map](https://web.dev/articles/source-maps) along with your minified files. Use the Source Map Upload API to upload your source maps to Honeybadger. See [Using Source Maps](/lib/javascript/errors/using-source-maps/) to learn more. ## Overview [Section titled “Overview”](#overview) To upload your source map files to Honeybadger, POST them to `https://api.honeybadger.io/v1/source_maps` with the following parameters: | Param | Required | Description | | -------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_key` | Required | The API key of your Honeybadger project (see the API Key tab in project settings). | | `minified_url` | Required | The URL of your minified JavaScript file in production. `*` can be used as a [wildcard](#wildcards). Must be an absolute URL (query strings are ignored). | | `minified_file` | Required | The minified file itself. | | `source_map` | Required | The source map for your minified file. | | revision | Optional, default: `master` | The deploy revision (i.e. commit sha) that your source map applies to. This could also be a code version. For best results, set it to something unique every time your code changes. The `revision` option must also be configured in [honeybadger.js](/lib/javascript/reference/configuration/). | | \ | Optional | One or more additional source files which may be referenced by your source map. The name should be the URL that would normally be used to access the file, and the value should be the file itself. Many source map generators include the sources in the `sourcesContent` key inside the source map, so you may not need to send these. `*` in the name can be used as a [wildcard](#wildcards). | Here’s an example using `curl`: ```bash curl https://api.honeybadger.io/v1/source_maps \ -F api_key=Your project API key \ -F revision=dcc69529edf375c72df39b0e9195d60d59db18ff \ -F minified_url=https://example.com/assets/application.min.js \ -F source_map=@path/to/application.js.map \ -F minified_file=@path/to/application.min.js \ -F http://example.com/assets/application.js=@path/to/application.js \ -F http://example.com/assets/utils.js=@path/to/utils.js ``` ## Response codes [Section titled “Response codes”](#response-codes) The `/v1/source_maps` API endpoint responds with the following codes: | Code | Status | Description | | ----- | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `201` | Created | The files were uploaded successfully. | | `400` | Bad Request | You’re missing a required parameter or have exceeded the maximum file size of 80MB per file (check the error message). | | `401` | Unauthorized | Your API key is invalid. | ## Wildcards [Section titled “Wildcards”](#wildcards) In some cases you may want to upload the same source map for different URLs—for instance, if you serve your files from multiple subdomains, or via both HTTP and HTTPS. An asterisk (`*`) can be used in URLs to perform a wildcard match. For example, the following example will match both the `http://` and `https://` version of the URL: ```plaintext http*://example.com/assets/application.min.js ``` …matches the following URLs: ```plaintext http://example.com/assets/application.min.js https://example.com/assets/application.min.js ``` Wildcards are *not* supported in file names: ```plaintext // invalid (will be an exact match): https://example.com/assets/*.min.js ``` # Status pages API reference > API reference for managing status pages with endpoints to create, read, update, and delete resources. Create and manage status pages within your accounts. ## Get all status pages [Section titled “Get all status pages”](#get-all-status-pages) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages ``` Returns a list of all status pages in this account. ```json { "results": [ { "id": "rMGSZB", "name": "My Awesome Status Page", "account_id": "Me3upk", "domain": "your.custom.domain", "url": "your.custom.domain", "created_at": "2022-01-29T11:26:19.120153Z", "domain_verified_at": "2022-01-29T14:02:32.570227Z", "sites": [], "check_ins": [ { "check_in_id": "XXXXXX", "display_name": "Nightly billing", "state": "reporting", "reported_at": "2022-01-29T00:00:02.523254Z" } ] }, { "id": "vWbSWr", "name": "Really Awesome Status Page", "account_id": "Me3upk", "domain": null, "url": "vWbSWr.status.hbuptime.com", "created_at": "2022-01-29T11:09:32.570227Z", "domain_verified_at": null, "sites": [ { "site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6537", "display_name": "Main site", "state": "up", "last_checked_at": "2022-01-29T11:09:30.982801Z" }, { "site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6557", "display_name": "API", "state": "up", "last_checked_at": "2022-01-29T11:04:28.675309Z" } ], "check_ins": [] } ], "links": { "self": "http://localhost:3000/v2/accounts/4bYurk/status_pages" } } ``` ## Get a single status page’s details [Section titled “Get a single status page’s details”](#get-a-single-status-pages-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages/ID ``` ```json { "id": "vWbSWr", "name": "Really Awesome Status Page", "account_id": "Me3upk", "domain": null, "url": "vWbSWr.status.hbuptime.com", "created_at": "2022-01-29T11:09:32.570227Z", "domain_verified_at": null, "sites": [ { "site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6537", "display_name": "Main site", "state": "up", "last_checked_at": "2022-01-29T11:09:30.982801Z" }, { "site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6557", "display_name": "API", "state": "up", "last_checked_at": "2022-01-29T11:04:28.675309Z" } ], "check_ins": [] } ``` ## Create a status page [Section titled “Create a status page”](#create-a-status-page) ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \ -d '{ "status_page": { "name": "Really Awesome Status Page", "domain": "your.custom.domain", "sites": [ { "site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6537", "display_name": "Main site" } ] } }' https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages ``` You can specify these fields within the `status page` object: | Field name | Type | Description | | --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | The name of the status page | | `domain` | string | (Optional) A custom domain for the status page. Setting this will trigger the domain DNS verification check. | | `sites` | object\[] | (Optional) Details of sites to add to this status page. Each object references a site in a project in this account, and must contain the `site_id` and an optional `display_name` and `position`. The `position` field is a zero-indexed integer that controls how your sites will be ordered on the status page. | | `check_ins` | object\[] | (Optional) Details of check-ins to add to this status page. Each object references a check-in in a project in this account, and must contain the `check_in_id` and an optional `display_name` and `position`. The `position` field is a zero-indexed integer that controls how your check-ins will be ordered on the status page. | | `hide_branding` | boolean | Whether or not to hide the Honeybadger branding in the footer of the status page. Only available on the Team plan and above. | | features | object | Additional customization options only available on the Team plan and above. Available options:- `home_link`: URL to hyperlink the status page title or logo to. - `up_caption`: The caption displayed when all checks are passing. - `down_caption`: The caption displayed when all checks are failing. - `mixed_caption`: The caption displayed when some checks are failing. - `custom_css`: Custom CSS that will be injected into the status page. | Returns a 201 Created response containing the created status page’s details. ## Update a status page [Section titled “Update a status page”](#update-a-status-page) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' \ -d '{ "status_page": { "domain": "different.custom.domain", "sites": [ { "site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6537", "display_name": "Main site" } ] } }' https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages/ID ``` You can specify one or more of these fields within the `status page` object: | Field name | Type | Description | | --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | The name of the status page | | `domain` | string | A custom domain for the status page. Changing this will trigger the domain DNS verification check. | | `sites` | object\[] | Details of sites to add to this status page. Each object references a site in a project in this account, and must contain the `site_id` and an optional `display_name`. | | `hide_branding` | boolean | Whether or not to hide the Honeybadger branding in the footer of the status page. Only available on the Team plan and above. | | `features` | object | Additional customization options only available on the Team plan and above. Available options:- `home_link`: URL to hyperlink the status page title or logo to. - `up_caption`: The caption displayed when all checks are passing. - `down_caption`: The caption displayed when all checks are failing. - `mixed_caption`: The caption displayed when some checks are failing. - `custom_css`: Custom CSS that will be injected into the status page. | Returns an empty response (204 No Content) if successful. ## Delete a status page [Section titled “Delete a status page”](#delete-a-status-page) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages/ID ``` Returns an empty response (204 No Content) if successful. # Streams API reference > API reference for listing Insights streams and retrieving their IDs for use in queries and alarms. Insights events live in streams. Every project has two built-in streams: `default`, which receives events sent by your applications, and `internal`, which receives Honeybadger-generated events such as error occurrences, deployments, uptime checks, and check-ins. Use stream IDs in the `stream_ids` request field to choose which streams [Insights queries](/api/insights/) and [alarms](/api/alarms/) search. ## Get all streams [Section titled “Get all streams”](#get-all-streams) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/streams ``` Returns a list of the project’s streams. ```json { "results": [ { "id": "a1b2c3d4e5f6", "name": "Default", "slug": "default", "internal": false, "project_id": 1, "created_at": "2026-07-15T13:56:29.513358Z" }, { "id": "f6e5d4c3b2a1", "name": "Internal", "slug": "internal", "internal": true, "project_id": 1, "created_at": "2026-07-15T13:56:29.513358Z" } ], "links": { "self": "https://app.honeybadger.io/v2/projects/1/streams" } } ``` | Field name | Type | Description | | ------------ | ------- | ------------------------------------------------------------------------------------------------------ | | `id` | string | The stream ID accepted by the `stream_ids` request field in Insights queries and alarms. | | `name` | string | The stream’s display name. | | `slug` | string | The stable identifier for the stream’s role: `default` or `internal`. | | `internal` | boolean | Whether the stream holds Honeybadger-generated events (`notice`, `deploy`, `uptime_check`, and so on). | | `project_id` | integer | The project the stream belongs to. | | `created_at` | string | The ISO 8601 timestamp when the stream was created. | Streams also appear in the `streams` array of [project payloads](/api/projects/). ## Notes [Section titled “Notes”](#notes) * Stream selection is per-project. IDs that don’t belong to the project (whether unknown or from another project) are silently ignored. A request containing those IDs may therefore return fewer results than expected instead of an error. * Streams are provisioned asynchronously after project creation, so a just-created project’s stream list may be empty or partial for a short time. Retry the request before concluding that streams are missing. # Teams API reference > API reference for managing teams with endpoints to retrieve and update team members and permissions. ## Get a team list or team details [Section titled “Get a team list or team details”](#get-a-team-list-or-team-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams?account_id=ACCOUNT_ID curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID ``` Returns a list of teams ```json { "id": 1, "name": "The Avengers", "created_at": "2013-01-11T15:40:35Z", "owner": { "id": 1, "email": "thor@example.org", "name": "Thor" }, "members": [...], "projects": [...], "invitations": [...] } ``` If the `account_id` parameter is not supplied when requesting the list of teams, all teams will be returned across all accounts to which the provided AUTH\_TOKEN has access. ## Create a team [Section titled “Create a team”](#create-a-team) ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"team":{"name":"My team"}}' https://app.honeybadger.io/v2/teams?account_id=ACCOUNT_ID ``` You can specify these fields: | Field name | Type | Description | | ---------- | ------ | ----------- | | `name` | string | | If the `account_id` query parameter is not provided, the team will be associated with the first account accessible by the user associated with the AUTH\_TOKEN. ## Update a team [Section titled “Update a team”](#update-a-team) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"team":{"name":"Updated team name"}}' https://app.honeybadger.io/v2/teams/ID ``` ## Delete a team [Section titled “Delete a team”](#delete-a-team) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID ``` ## Get a list of team members or team member details [Section titled “Get a list of team members or team member details”](#get-a-list-of-team-members-or-team-member-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID/team_members ``` Returns all the members or a single team member for the given team: ```json { "id": 1, "created_at": "2012-12-13T15:00:47Z", "admin": true, "name": "", "email": "westley@example.com" } ``` ## Update a team member [Section titled “Update a team member”](#update-a-team-member) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"team_member":{"admin":true}}' https://app.honeybadger.io/v2/teams/ID/team_members/ID ``` The list of valid fields is as follows: | Field name | Type | Description | | ---------- | ------- | ----------- | | `admin` | boolean | | ## Delete a team member [Section titled “Delete a team member”](#delete-a-team-member) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID/team_members/ID ``` ## Create a team invitation [Section titled “Create a team invitation”](#create-a-team-invitation) ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \ -d '{"team_invitation":{"email":"inigo@example.com"}}' \ https://app.honeybadger.io/v2/teams/ID/team_invitations ``` You can specify these fields: | Field name | Type | Description | | ---------- | ------- | ------------------------------------------------------------------ | | `email` | string | The invited user’s email address. | | `admin` | boolean | (Optional) Set this to true to make the invited user a team admin. | | `message` | string | (Optional) The message to be included in the invitation email. | Returns the created team invitation: ```json { "id": 9, "email": "inigo@example.com", "created_by": { "email": "westley@example.com", "name": "Westley" }, "accepted_by": null, "admin": false, "accepted_at": null, "created_at": "2013-01-08T15:42:16Z", "message": null } ``` ## Update a team invitation [Section titled “Update a team invitation”](#update-a-team-invitation) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' \ -d '{"team_invitation":{"admin": true}}' \ https://app.honeybadger.io/v2/teams/ID/team_invitations/ID ``` You can specify either of these fields: | Field name | Type | Description | | ---------- | ------- | ------------------------------------------------------- | | `admin` | boolean | Set this to true to make the invited user a team admin. | | `message` | string | The message to be included in the invitation email. | ## Get a team invitation list or team invitation details [Section titled “Get a team invitation list or team invitation details”](#get-a-team-invitation-list-or-team-invitation-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID/team_invitations curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID/team_invitations/ID ``` Returns a list of team invitations or a single team invitation for the given team: ```json { "id": 9, "email": "inigo@example.com", "created_by": { "email": "westley@example.com", "name": "Westley" }, "accepted_by": { "email": "inigo@example.com", "name": "Inigo Montoya" }, "admin": true, "accepted_at": "2013-01-08T15:42:41Z", "created_at": "2013-01-08T15:42:16Z", "message": null } ``` ## Delete a team invitation [Section titled “Delete a team invitation”](#delete-a-team-invitation) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID/team_invitations/ID ``` # Uptime API reference > API reference for managing uptime monitors with endpoints to create, read, update, and delete resources. ## Get a site list or site details [Section titled “Get a site list or site details”](#get-a-site-list-or-site-details) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites/ID ``` Returns a list of sites or a single sites for the given project with the following format: ```json { "active": true, "frequency": 5, "id": "9eed6a7e-af77-4cc6-8c55-b7b17555330d", "last_checked_at": "2016-06-15T12:57:29.646956Z", "match": null, "match_type": "success", "name": "Main site", "state": "down", "url": "http://www.example.com" } ``` ## Create a site [Section titled “Create a site”](#create-a-site) ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"site":{"name":"My site","url":"https://www.example.com/"}}' https://app.honeybadger.io/v2/projects/ID/sites ``` Here is a list of the fields that can be specified: | Field name | Type | Description | | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | string | | | `url` | string | | | `frequency` | integer | Number of minutes between checks (valid values are 1, 5, or 15). | | `match` | string | The status code that will be returned or string to be present/absent to indicate a passing check, depending on the value of `match_type`. Unused when the match\_type is “success”. | | `match_type` | string | One of “success” for a status code of 200-299, “exact” for a particular status code (provided via the `match` field), “include” to require the text in `match` to be present on the page, and “exclude” to require the text in `match` to not be present on the page. | | `request_method` | string | One of GET, POST, PUT, PATCH, or DELETE. | | `request_body` | string | The body content to be sent with the check. | | `request_headers` | array | Array of hashes (e.g., `[{ key: "Content-type", value: "application/json" }]`) that will be added to the request headers. | | `locations` | array | Array of strings (e.g, `['London', 'Virginia']`) that will limit the locations that will be used for the checks. Providing an empty array (the default) will cause all locations to be used. Available locations are Virginia, Oregon, Frankfurt, Singapore, and London. | | `validate_ssl` | boolean | Whether to have the check fail if the SSL certificate is not valid or is expired. | | `timeout` | integer | **Business and Enterprise customers only.** How long the uptime check will wait for a response before reporting the site as down (in seconds). The default is 30 seconds and the maximum is 120 seconds. | | outage\_threshold | integer | The number of unsuccessful checks required to trigger an alert. If this is blank, then an alert will be sent after half of the locations return with failed checks. | | `active` | boolean | Whether to run the checks. | ## Update a site [Section titled “Update a site”](#update-a-site) ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"site":{"name":"Updated site name"}}' https://app.honeybadger.io/v2/projects/ID/sites/ID ``` Update requests can change the same fields as create requests. ## Delete a site [Section titled “Delete a site”](#delete-a-site) ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/sites/ID ``` ## Get a list of outages for a site [Section titled “Get a list of outages for a site”](#get-a-list-of-outages-for-a-site) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites/ID/outages ``` Returns a list of outages with the following format: ```json { "down_at": "2015-02-17T18:20:44.776959Z", "up_at": "2015-02-17T18:22:35.614678Z", "created_at": "2015-02-17T18:20:44.777914Z", "status": 301, "reason": "Expected 2xx status code. Got 301", "headers": { "Date": "Tue, 17 Feb 2015 18:20:44 GMT", "Server": "DNSME HTTP Redirection", "Location": "http://text.vote/polls", "Connection": "close", "Content-Length": "0" } } ``` The outage list can be filtered with these URL parameters: | Parameter | Description | | ---------------- | ---------------------------------------------------- | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `created_before` | A Unix timestamp (number of seconds since the epoch) | | `limit` | Number of results to return (max and default are 25) | The outage list is always ordered by creation time descending. ## Get a list of uptime checks for a site [Section titled “Get a list of uptime checks for a site”](#get-a-list-of-uptime-checks-for-a-site) ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites/ID/uptime_checks ``` Returns a list of uptime checks with the following format: ```json { "created_at": "2016-06-16T20:19:32.852569Z", "duration": 1201, "location": "Singapore", "up": true } ``` The uptime check list can be filtered with these URL parameters: | Parameter | Description | | ---------------- | ---------------------------------------------------- | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `created_before` | A Unix timestamp (number of seconds since the epoch) | | `limit` | Number of results to return (max and default are 25) | The uptime check list is always ordered by creation time descending.