API: Retrieving Data

Search for events or filter by field across all log events. The “Search” & “Event” endpoints will work together to return a set of your events. The “Fields” endpoint will return the list of all fields we’ve parsed from your events. Provide a field name to receive the values and counts.

The Event Search API is split across two different endpoints: one to define the search and another for retrieval of resulting events.
To define a search, start with a request like the one below. Substitute your account name for “<account>”.
$ curl -u <username>:<password> "http://<account>.loggly.com/apiv2/search?q=*&from=-2h&until=now&size=10"
{
  "rsid": {
    "status": "SCHEDULED",
    "date_from": 1374686593000,
    "elapsed_time": 0.01730203628540039,
    "date_to": 1375550593000,
    "id": " 728480292
  }
}

This returns an RSID, shown in red, which the client will need to retrieve events via a call to the “/events” endpoint. Your next call to retrieve the events will remain open until the call returns or times out. We currently don’t support polling to check if the results are ready, so you can ignore the status field. If you are sending requests at a high rate and receive a 503 error, you may have hit the rate limit. If you get a 504 or 500 with a description of “timeout” you can retry making the request again. You can read a full description of our HTTP response codes.

Search Endpoint Parameters
q required query string, check out the Search Query help
from optional Start time for the search. Defaults to “-24h”.
(See valid time parameters.)
until optional End time for the search. Defaults to “now”.
(See valid time parameters.)
order optional Direction of results returned, either “asc” or “desc”. Defaults to “desc”.
size required Number of rows returned by search. Defaults to 50.

Here are a few more examples. If you’d like to make an API request from a browser, you won’t need to encode the special characters.

API event request with multiple parameters, including tags:

https://account.loggly.com/apiv2/search?q=json.responseTime:"288" tag:apache json.treatment.order:"up" NOT json.location.pathname:*&from=2013-10-17T21%3A24%3A18.007Z&until=2013-10-18T21%3A24%3A18.007Z

or, with relative dates:

https://account.loggly.com/apiv2/search?q=json.responseTime:"288" tag:apache json.treatment.order:"up" NOT json.location.pathname:*&from=-1d&until=now

or, with a string as a value:

https://account.loggly.com/apiv2/search?q=json.responseTime:"288" json.treatment.order:"up" NOT json.location.pathname:* json.context.terms:"rock n roll"&from=-1d&until=now

The browser will do the encoding on the above API requests. In order to cURL from a command line terminal, you’ll need to encode special characters, including spaces and quotes.

$ curl -u <username>:<password> "http://<account>.loggly.com/apiv2/search?q=json.responseTime:%22288%22%20json.treatment.order:%22desc%22%20NOT%20json.location.pathname:*%20json.context.terms:%22rock%20n%20roll%22&from=-1d&until=now"

Events Endpoint

This endpoint will return your search results for the given RSID, and allows you to retrieve events in pages. It will respond once the search results are ready.

$ curl -u <username>:<password> "http://<account>.loggly.com/apiv2/events?rsid=728480292"
{
  "total_events": 3292470,
  "page": 0, 
  "events": [
    {
      "tags": [
        "chipper", 
        "frontend"
      ], 
      "timestamp": 1377431712208, 
      "logmsg": " {\"timestamp\": \"13-08-25 11:55:12,208191\", \"baremsg\": \"Alert is due to run\"}", 
      "event": {
        "syslog": {
          "priority": "142",
          "timestamp": "2013-08-25T11:55:12.208596+00:00", 
          "host": "frontend01", 
          "severity": "Informational", 
          "facility": "local use 1"
        }, 
        "json": {
          "timestamp": "13-08-25 11:55:12,208191", 
          "baremsg": " is due to run", 
          "level": "INFO"
        }
      }, 
      "logtypes": [
        "syslog",
        "json"
      ],
      "id": "c693c674-0d7d-11e3-80e9-20ae90200ddd"
    }
  ]
}
Events Endpoint Request Parameters
rsid required The ID that was returned in response to your /search request.
page optional Which page of results you’d like returned. Defaults to 0 if not defined. Pages are also zero-indexed, starting at 0 for the first page.
format optional Data format you’d like to have your results returned. Options are “raw”, “csv”, or “json”. If “json” is used as a format, it will provide a file to download. Default is “json”.
columns optional If you’d like to limit your result set to a set list of fields. Takes a comma separated list.
Events Endpoint Response Parameters
total_events Total number of matching events for the entire time range
page Which page of the result set
tags An array of any tags associated with the event
timestamp See timestamps to understand how a reference timestamp is derived.
logmsg The message portion of the log event. (Any headers aren’t included.)
event Any parsed fields are included.
logtypes An array of log types that were detected.
id Loggly’s event ID.

*There is currently a maximum limit of 5000 individual events returned per search query. We don’t support paging beyond this 5000 event limit either. If a search encompasses more than 5000 events, you will have to do another query to retrieve more events.

Search Tricks

All in one command:

$ query="test"; cred="<username>:<password>"; account="example"; curl -s -u "$cred" "http://$account.loggly.com/apiv2/search?q=$query&from=-2h&until=now&size=10" >/tmp/searchrsid.tmp && curl -u "$cred" "http://$account.loggly.com/apiv2/events?rsid=`python -c \"import json; j=json.load(open('/tmp/searchrsid.tmp')); print j['rsid']['id'];\"`"

Field Search

The parameters included with a field search are the same as the parameters you include for the Search endpoint shown above. Use the fields endpoint without any parameters to get a list of all available fields.
$ curl -u <username>:<password> "http://<account>.loggly.com/apiv2/fields/"

Or, include some search criteria:

$ curl -u <username>:<password> "http://<account>.loggly.com/apiv2/fields?q=*&from=-2h&until=now&facet_size=10"

This returns a list of available field names for which you can request more information.

{
  "fields": [
    {
      "name": "syslog.host"
    },
    {
      "name": "logtype"
    },
    {
      "name": "json.context.rows"
    },
    {
      "name": "json.viewport.width"
    }
  ],
  "rsid": {
    "status": "SCHEDULED",
    "date_from": 1382136613000,
    "elapsed_time": 0.023257017135620117,
    "date_to": 1383000613000,
    "id": "439948601"
  }
}

*There is currently a maximum limit of 500 fields returned via this endpoint. Our Dynamic Field Explorer also have a limit of maximum 500 fields that could be displayed in the Loggly UI.

Fields Endpoint Request Parameters
q optional query string, check out the Search Query help
from optional Start time for the search. Defaults to “-24h”.
(See valid time parameters.)
until optional End time for the search. Defaults to “now”.
(See valid time parameters.)
facet_size optional Number of fields to return, default to 10.

Filter by Field

If you’re looking for counts and values for a specific field within your result set, append the field name. Options are the same as the fields/ endpoint, but the maximum number of field values (facet_size) that can be returned is 300. Make sure to include the trailing slash:

$ curl -u <username>:<password> "http://<account>.loggly.com/apiv2/fields/syslog.host/"

Or, include some search criteria:

$ curl -u <username>:<password> "http://<account>.loggly.com/apiv2/fields/syslog.host/?q=apache&from=-2h&until=now"

This returns a list of fields & the counts for the given field.

{
  "syslog.host": [
    {
      "count": 252,
      "term": "host01.example.com"
    },
    {
      "count": 4,
      "term": "host02.example.com"
    }
  ],
  "total_events": 256
}

CORS Support

Cross Origin Resource Sharing is enabled across all of our API endpoints. JavaScript developers can take advantage of this support to further integrate Loggly into their applications.

CORS is an addition to the browser security model that allows XHR requests to be made from one domain to another. CORS allows Javascript applications to access resources on domains other than the original document’s domain, working around the same-origin policy. While Javascript application developers have crafted techniques like JSONP, Flash proxies, XHR receivers, and server-side proxies to circumvent the same-origin policy, CORS makes these hacks unnecessary.

To take advantage of CORS both the server and the browser need to support the standard. The browser needs to initiate a negotiation with the server and the server must signal to the browser which domains are allowed to make cross-domain requests.

Here’s some sample code that you can use to take advantage of this feature:

Thanks for the feedback! We'll use it to improve our support documentation.


Top