Search API

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

The log search API endpoint is one part of Papertrail’s HTTP API. All API calls use the same authentication and request/response format. To manage account resources, such as to create groups or register new senders, see Settings API.

API Endpoint

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

Query parameters

All parameters are optional.

Timestamps for min_time and max_time should be in epoch time UTC.

Example requests

Basic querying

Request the 1000 most recent events:

curl -v -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/events/search.json

Search for events containing error:

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

Advanced querying

All search queries that work in the Papertrail Web interface also work in the API.

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

ssh OR ("authentication failure" AND success)

would create this request:

curl -v -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/events/search.json?q=ssh%20OR%20%28%22authentication%20failure%22%20AND%20success%29

Searching for the simpler phrase Critical error:

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

Constraining Scope

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

curl -v -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/events/search.json?q=unable&system_id=1234

searches system ID 1234 for unable, and

curl -v -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/events/search.json?q=SELECT&group_id=2345

searches group ID 2345 for SELECT.

Unique system names (name in the system JSON hash; see Systems LIST) that contain only numbers, letters, and underscores can be used for system_id as well. This can simplify linking to results for a single system, since no name-to-mapping API query is necessary. For example:

curl -v -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/events/search.json?system_id=www42&q=user

would search system www42 for user.

Constraining time

To search only a particular time range, provide a minimum or maximum event ID or time. For example, to retrieve events from Monday, June 19 2017 at 9:35 am Pacific to Monday, June 19 2017 at 9:40am Pacific:

curl -v -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/events/search.json?min_time=1497890100&max_time=1497890400

Responses

The search endpoint returns a JSON object containing these keys:

In addition to min_id and max_id, the response object may also contain min_time_at or max_time_at. These are the oldest or newest timestamps searched during this request. (max_time_at is used with tail=false.) These keys are useful for displaying the time the search spanned in a human-friendly way, but since multiple events may have occured during the same second, they should not be used to select a time range for subsequent queries.

Event keys

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

Data types

Result set types

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

Per-request time limit

Papertrail’s workload varies significantly based on the number of possible events and the complexity of the query. To ensure that the caller does not block forever, the search API automatically enforces a per-request time limit of about 5 seconds. When the response contains reached_time_limit, this time limit was reached.

Examples

Events, reached beginning

{
  "min_id":"7711561783320576",
  "max_id":"7711582041804800",
  "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
}

No events (reached beginning)

{
  "min_id":"811435198242832388",
  "max_id":"812522210429444144",
  "events":[],
  "reached_beginning":true,
  "min_time_at":"2017-06-13T17:00:49-07:00"
}

Events, reached time limit

{
  "min_id":"812519612313911352",
  "max_id":"812521233945083916",
  "events":["...some number of events here..."],
  "reached_time_limit":true,
  "min_time_at":"2017-06-16T16:49:48-07:00"}

Events, reached record limit

{
  "min_id":"812520720696492064",
  "max_id":"812520758218723347",
  "events":["...1000 events here..."],
  "reached_record_limit":true,
  "min_time_at":"2017-06-16T16:54:18-07:00"
}

Implementing search behavior

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

Retrieving older events

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

To scroll back through progressively older events (similar to the behavior of the Papertrail viewer filling in older events over time once it finds recent results), pass the min_id from the Papertrail response back in as the max_id for the next request.

Retrieving events for a time period

For example, to retrieve events that occurred between 3:00am and 9:00am, with the most recent results first:

If the events of greater interest are the older events, it’s also possible to start at the earlier time and work forward by passing tail=false, taking the returned max_id and passing it in as min_id.

Questions

If you have any questions about how to handle incomplete result sets or implement a particular style of search, contact us.