V2 API: Projects and Groups

Airbrake provides easy access to all your data via an XML-based, RESTful API.

There are also a number of Alternative Plugins, Widgets, and Extras that Airbrake users have built. We also have a tutorial using Python as an example.

There is one prerequisite to using the API: you must have an auth_token. When logged in, you can find your auth_token near the bottom of the My Settings tab after clicking the Settings button.

If you are looking to send notifications to Airbrake (perhaps for your own custom notifier), instead of reading data, you'll want to read up on the Notifier API.

A note about SSL

If your plan supports SSL, you must access the API over an HTTPS connection. Standard HTTP requests to the API for these accounts will return an "HTTP 403 Forbidden" status.

Accessing the API using Ruby

If you are using Ruby, then you can use ActiveResource to write a client to easily connect to the API. Here is what it'd look like:

# code at http://gist.github.com/3350
# tests at http://gist.github.com/3354

class Airbrake < ActiveResource::Base
  self.site = "http://your_account.airbrake.io"

  class << self
    @@auth_token = 'your_auth_token'

    def find(*arguments)
      arguments = append_auth_token_to_params(*arguments)

    def append_auth_token_to_params(*arguments)
      opts = arguments.last.is_a?(Hash) ? arguments.pop : {}
      opts = opts.has_key?(:params) ? opts : opts.merge(:params => {}) 
      opts[:params] = opts[:params].merge(:auth_token => @@auth_token)
      arguments << opts

class Error < Airbrake  

# Errors are paginated. You get 30 at a time.

@errors = Error.find :all
@errors = Error.find :all, :params => { :page => 2 }

Accessing the API Directly

The API is a normal Rails REST service, and while Ruby is our preferred language, you can use any language you want to query the API.

  • To get the XML for the 30 most recently active errors:
  • To get the XML for the next 30 most recently active errors:
  • To get the XML for a specific error:
  • By default, errors which are marked as resolved are not included. To include these, add a parameter show_resolved=true to your HTTP request.
  • To set a particular error as resolved, use a PUT. For example, with RestClient:
subdomain = "your subdomain"
project_id = "..."
group_id = "..."
key = "...."
url = "https://#{subdomain}.airbrake.io/api/v3/projects/#{project_id}/groups/#{group_id}?key=#{key}"
RestClient.put(url, {}, content_type: "application/json"), :group => { :resolved => true})

When getting multiple errors at once, the environment, backtrace, session, and request information will not be returned along with the errors. To view this additional information request the xml for the individual error:


Here is the XML for a typical error

<?xml version="1.0" encoding="UTF-8"?>
  <created-at type="datetime">2008-07-09T20:06:44-07:00</created-at>
  <error-message>NoMethodError: undefined method `password' for nil:NilClass</error-message>

  <id type="integer">5529</id>
  <last-notice-at type="datetime">2008-07-31T04:21:52-07:00</last-notice-at>
  <last-notice-id type="integer">203799</last-notice-id>
  <line-number type="integer">186</line-number>
  <notices-count type="integer">30</notices-count>

  <project-id type="integer">2</project-id>
  <updated-at type="datetime">2008-07-31T04:21:52-07:00</updated-at>
  <visible type="boolean">true</visible>

To access a paginated list of notices for this error, request the notices index nested under the error:


To get detailed information on a specific notice:


To get a list of your projects:


To get a list of your deploys (for a project):


Note: If your account supports SSL, make sure to use https instead of http

Submitting Errors to Airbrake

In order to submit errors to Airbrake, you can either use the airbrake plugin for Rails, or access the API directly. For information about the notifier, API, see http://help.airbrake.io/faqs/api-2/notifier-api-v2.