API Guide

It's easy to pull your data out of Honeybadger using our Read API. It's so simple, you could probably even guess the URL structure. :)

Read API

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 it doesn't hurt to 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.

Project List / Project Details

https://app.honeybadger.io/v2/projects
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"
    }
  ]
}

Fault List / Fault Details

https://app.honeybadger.io/v2/projects/ID/faults
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.

Notice List

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.

Comment List / Comment Details

https://app.honeybadger.io/v2/projects/ID/faults/ID/comments
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"
}

Deploy List / Deploy Details

https://app.honeybadger.io/v2/projects/ID/deploys
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.

Site List / Site Details

https://app.honeybadger.io/v2/projects/ID/sites
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"
}

Site Outage List

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.

Site Uptime Check List

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-in List / Check-in Details

https://app.honeybadger.io/v2/projects/ID/check_ins
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": "pending",
  "schedule_type": "cron",
  "reported_at": null,
  "expected_at": null,
  "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"
}

Team List / Team Details

https://app.honeybadger.io/v2/teams
https://app.honeybadger.io/v2/teams/ID

Returns a list of team 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"
}

Team Invitation List / Team Invitation Details

https://app.honeybadger.io/v2/teams/ID/team_invitations
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
}

Occurrences

https://app.honeybadger.io/v2/projects/occurrences
https://app.honeybadger.io/v2/projects/ID/occurrences

Provides the number of times errors have been encountered in your application per project or across all your projects.

The data can be filtered with these URL parameters:

Parameter Description
period One of "hour", "day", or "week". 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", the data is grouped into the most recent 7 one-day buckets. All times and bucket boundaries are UTC.

Collector API

If you want to write your own library to send data to Honeybadger, these are the docs for you.

Before you get started, make sure we don't already support your language. Here's the official list:

And here are a few community-created clients:

It also wouldn't hurt to get in touch and make sure we don't have something in the works.

Overview

Your JSON payload should be submitted as the body of a POST request to https://api.honeybadger.io/v1/notices, 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, 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.

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:

{
  // Please use different values for the name and url keys of the 
  // `notifier` key, but use the same version as listed in the gist,
  // to help us manage the processing of the payload and alerting users to new features.
  "notifier":{
    "name":"Honeybadger Notifier",
    "url":"https://github.com/honeybadger-io/honeybadger-ruby",
    "version":"1.0.0"
  },
  // Here's where you're 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 `source` attribute is an optional code snippet that'll be shown with the backtrace.
  // The `backtrace` is a ruby-style backtrace.
  // 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"],
    "source":{
      "2":"",
      "3":"  def runtime_error",
      "4":"    raise RuntimeError.new(\"This is a runtime error, generated by the crywolf app\")",
      "5":"  end",
      "6":""
    },
    "backtrace":[
      {
        "number":"4",
        "file":"/crywolf/app/controllers/pages_controller.rb",
        "method":"runtime_error"
      },
      {
        "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"
          }
        ]
      }
    ]
  },

  // `request` contains information about the HTTP request that caused this exception. 
  "request":{

    // We display this data on the error's details page. 
    "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":{
      "path":"/Users/josh/code/crywolf"
    },

    // Your environment name
    "environment_name":"development",

    // The server's hostname
    "hostname":"Josh-MacBook-Air.local"
  }
}

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 to see how your payloads will be rendered in our UI.

Deployment Tracking API

Ruby users: make sure you check out our section on ruby deployment tracking before you re-invent the wheel.

If you need to manually notify Honeybadger of a deploy, you can use our API directly.

To do this, make a POST request to https://api.honeybadger.io/v1/deploys with the following parameters:

Parameter Description
api_key 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

Here's an example curl command to do a deploy notification:

curl --data "deploy[environment]=production&deploy[local_username]=Mary&deploy[revision]=12345&deploy[repository]=github.com/myuser/myproject.git&api_key=asdf" "https://api.honeybadger.io/v1/deploys"

If everything goes well, you'll get a response saying {"status":"OK"}