Data Access API

The Data Access 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 Ingestion API documentation.

Authentication

Authentication to the API is performed via HTTP Basic Auth. Each request should be sent with your personal authentication token (available from your profile page) 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):

curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects

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

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:

{
  "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

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:

{ 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.

Projects

Get a project list or project details

curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID

Returns a list or a single project with the following format:

{
  "active": true,
  "created_at": "2012-06-09T20:33:27.798800Z",
  "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"
  },
  "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"
    }
  ],
  "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"
    }
  ]
}

Create a project

curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"project":{"name":"My project"}}' https://app.honeybadger.io/v2/projects

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 the to 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.

Update a project

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

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

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.

[
  [ 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.

Faults and Notices

Get a fault list or fault details

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:

{
  "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,
  "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
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.

Get a count of faults

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
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:

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

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

Delete a fault

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/faults/ID

Get a list of notices

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:

{
  "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",
    "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

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:

[
  {
    "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.

Get a count of occurrences for a fault

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.

[
  [ 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

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.

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:

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

You can mark all faults for a project as resolved using this endpoint:

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.

This endpoint returns a successful response (200) with an empty body when the request is successful.

Comments

Get a comment list or comment details

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:

{
  "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

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

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

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/faults/ID/comments/ID

Deploys

Get a deploy list or deploy details

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:

{
  "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

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/deploys/ID

Sites

Get a site list or site details

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:

{
  "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"
}

Update a site

curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"site":{"name":"My site"}}' 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
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.
active boolean Whether to run the checks.

Update a site

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

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/sites/ID

Get a list of outages for a site

curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites/ID/outages

Returns a list of outages with the following format:

{
  "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

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:

{
  "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.

Check-ins

Get a check-in list or check-in details

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

{
  "state": "pending",
  "schedule_type": "simple",
  "reported_at": null,
  "expected_at": null,
  "missed_count": 0,
  "grace_period": 300,
  "id": "XXXXXX",
  "name": "Hourly clean up",
  "url": "https://api.honeybadger.io/v1/check_in/XXXXXX",
  "report_period": 3600
}

Cron check-in

{
  "state": "reporting",
  "schedule_type": "cron",
  "reported_at": "2018-01-16T12:36:11Z",
  "expected_at": "2018-01-17T12:36:11Z",
  "missed_count": 0,
  "grace_period": 0,
  "id": "YYYYYY",
  "name": "Hourly check",
  "url": "https://api.honeybadger.io/v1/check_in/YYYYYY",
  "cron_schedule": "30 * * * *",
  "cron_timezone": "UTC"
}

Create a check-in

curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"check-in":{"name":"Daily reports", "report_period":86400, "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
schedule_type string Valid values are "simple" or "cron". If you specify "cron", then the "cron_schedule" field is required.
report_period integer For simple check-ins, the number of seconds that can elapse before the check-in is reported as missing. E.g., 86000 would require a hit to the API daily to maintain the "reporting" status.
grace_period integer The number of seconds to allow a job to not report before it's reported as missing.
cron_schedule string For a schedule_type of "cron", the cron-compatible string 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.

Update a check-in

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.

Delete a check-in

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/check_ins/ID

Teams

Get a team list or team details

curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID

Returns a list of teams

{
  "id": 1,
  "name": "The Avengers",
  "created_at": "2013-01-11T15:40:35Z",
  "owner": {
    "id": 1,
    "email": "thor@example.org",
    "name": "Thor"
  },
  "members": [...],
  "projects": [...]
}

Create a team

curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"team":{"name":"My team"}}' https://app.honeybadger.io/v2/teams

You can specify these fields:

Field name Type Description
name string

Update a team

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

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID

Get a list of team members or team member details

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:

{
  "id": 1,
  "created_at": "2012-12-13T15:00:47Z",
  "admin": true,
  "name": "",
  "email": "westley@honeybadger.io"
}

Update a team member

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

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID/team_members/ID

Get a team invitation list or team invitation details

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:

{
  "id": 9,
  "token": "e62394d2",
  "email": "",
  "created_by": {
    "email": "westley@honeybadger.io",
    "name": "Westley"
  },
  "accepted_by": {
    "email": "inigo@honeybadger.io",
    "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

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID/team_invitations/ID