Search API

Apps or clients can make HTTP requests to Papertrail to programmatically search for events.

To manage account resources, such as to create groups or register new senders, see Settings API.

Introduction

The log search API endpoint is one part of Papertrail’s HTTP API. All API calls use the same authentication and request/response format.

The search API URL is https://papertrailapp.com/api/v1/events/search.json.

Examples

The most basic example is simply to hit the search API endpoint, https://papertrailapp.com/api/v1/events/search.json. Try it. After authenticating, you’ll receive the most recent 1000 log events. (This behavior differs from the CLI’s initial default of 100.)

curl

These examples use curl, a command-line HTTP client.

Authenticate with an API token and search events for Critical error as a quoted phrase:

curl -v -H "X-Papertrail-Token: abc123" "https://papertrailapp.com/api/v1/events/search.json?q='Critical error'"

Search request timing

The search API returns events meeting a set of constraints (like matching a search query or in a group) between a minimum and/or maximum ID or time.

Papertrail’s workload varies significantly based on the number of possible events and the complexity of the query, so some searches may take a while. To ensure that the caller does not block forever, the search API automatically enforces a per-request time limit of about 5 seconds. The response provides results found so far (if any), plus extra fields min_id and max_id so that the calling client can choose to continue the search without receiving the same set of results again.

Common situations

For example, consider 2 common cases:

Requests

Optional query parameters

Search query (q)

To search for a specific message or string, add the optional parameter q (as in query). All search queries that work in the Papertrail Web interface work in the API.

All parameters should be URL-encoded, as is standard for GET query strings. For example, the search string:

bob OR ("some phrase" AND sally)

would be this URL-encoded GET query string:

q=bob%20OR%20(%22some%20phrase%22%20AND%20sally)

Constrain Scope (group_id or system_id)

To limit results to a specific group or system, include system_id or group_id in the query string. For example:

search.json?system_id=1234
search.json?group_id=2345

System names (name in the system JSON hash; see Systems LIST) that contain only numbers, letters, and underscores can be used for system_id in lieu of the Papertrail ID.

This can simplify linking to results for a single system, since no name-to-mapping API query is necessary. For example:

search.json?system_id=www42
search.json?system_id=my-big-server

Responses

Papertrail responds with a JSON hash containing 3 important keys:

Either reached_beginning or reached_time_limit may be true to indicate why the request ended. See Response types.

Displaying the time range searched

In addition to min_id and max_id, the response hash also contains min_time_at and max_time_at. These are the oldest and newest timestamps searched during this request in epoch time. They are purely informational, since multiple events may have occured during the same second, but are useful for displaying the time the search spanned in a human-friendly way.

Event keys

Within each log event hash, the following keys are defined:

received_at and display_received_at are in the time zone of the API token owner (see the profile).

Example

Here is a response with 2 log events:

{
  "max_id":"7711582041804800",
  "min_id":"7711561783320576",
  "events":[
    {"hostname":"abc","received_at":"2011-05-18T20:30:02-07:00","severity":"Info","facility":"Cron","source_id":2,"message":"message body","program":"CROND","source_ip":"208.75.57.121","display_received_at":"May 18 20:30:02","id":7711561783320576,"source_name":"abc"},
    {"hostname":"def","received_at":"2011-05-18T20:30:02-07:00","severity":"Info","facility":"Cron","source_id":19,"message":"A short event","program":"CROND","source_ip":"208.75.57.120","display_received_at":"May 18 20:30:02","id":7711562567655424,"source_name":"server1"}
  ],
  "reached_beginning":true
}

Value types

Papertrail uses 64-bit event IDs, which Javascript has trouble with, so the id value is a string. The other values are consistently set to the type you would expect. No values should be null except for program (when none is defined by the message). An empty message body is a blank string (‘’).

Empty result set

A response containing no matching events will return an empty events array, such as:

{"max_id":"0","reached_beginning":true,"events":[],"min_id":"0"}

Response types

Each search query will return one of three types of responses, and the client can use the type to decide what to do next. The 3 possible responses are:

If you have any questions about how a client can best handle these responses, contact us.

How search works

Retrieving current logs (live tail)

Clients may implement a “live tail” (tail -f-style) display by performing multiple successive searches for the same search query (or no search query). To do this, pass the max_id value from the prior result set back to the Papertrail API as the min_id parameter.

When the search query changes, start a fresh tail by omitting the min_id.

Retrieving older events

By event ID

To get older events (rather than current events), pass a max_id to Papertrail and it will return the most recent events that are older than that ID.

To scroll back through older events for a progressively-older tail, the min_id from one Papertrail response would be passed back in as the max_id for the next response, to receive events older than that response.

The id values for a series of events indicate relative event order and will only increase, but id values are not sequential.

By time

If the client has a timestamp but not an event ID, pass max_time or min_time with your first request (rather than max_id or min_id). These should be in epoch time UTC.

After the first response, provide max_id as in By event ID if successive queries are needed.