Sumo Logic exposes the Search Job API for access to resources and log data from third-party scripts and applications. Targeting experienced Sumo Administrators, this webinar shows you how to leverage the Search Job API to interact with the Sumo Logic service. Everyone attending should be familiar with the concepts of RESTful web services and JSON.

1. Sumo Logic Confidential
Sumo Logic API
Welcome.
You are currently in
listen-only mode.
To give everyone a
chance to successfully
connect, we’ll start at
10:05 AM Pacific.
How-To Webinar
Frank Reno, Customer Success
March 2016

2. Sumo Logic Confidential
Available APIs
Performing Searches
Managing Collectors
Interacting with Dashboards (Beta)

3. Sumo Logic Confidential
General API Details
• Authentication
– Initial request MUST include a HTTP Basic Authentication header using a
username/password or access id/access key
– API Authentications are limited to 15 calls per minute
– Multiple requests should use cookies
• The initial request will return a cookie containing two attributes: JSESSIONID and
AWSELB. These can be included in subsequent requests to reduce the number of
authentication calls.

4. Sumo Logic Confidential
• API requests are limited to 4 calls per second
• Data Formats
– All data is sent and received in JSON
• API URL
– Depends on your service region:
General API Details
Service URL API URL
https://service.sumologic.com https://api.sumologic.com/api/v1/
https://service.us2.sumologic.com https://api.us2.sumologic.com/api/v1/
https://service.us4.sumologic.com https://api.us4.sumologic.com/api/v1/
https://service.eu.sumologic.com https://api.eu.sumologic.com/api/v1/
https://service.au.sumologic.com https://api.au.sumologic.com/api/v1/

5. Sumo Logic Confidential
• Errors
– Errors are returned with an HTTP status code and JSON document.
– General Error Codes
• auth.failed – The authentication has failed
• internal.error – Internal server error
• unauthorized – Incorrect username/password
• service.unavailable – The service is unavailable
General API Details

6. Sumo Logic Confidential
• Ideal for fast, non-trivial queries
• Synchronous
• Limitations
– Search must complete within 1 minute or it will timeout
– A max of about 100K results will be returned. If you need more results, you will
need to execute subsequent requests with smaller time rages or use the Search
Job API.
Search API

7. Sumo Logic Confidential
• Endpoint: /logs/search
• Method: GET
*Time range values can be specified in ISO 8601 format or epoch milliseconds.
• https://api.sumologic.com/api/v1/logs/search?q=error&from=2012-04-
04T13:01:02&to=2012-04-04T15:01:02
Search API
Parameter Required Default Description
q Yes N/A The full search query to be executed.
from No -15m Start of the time range.
to No Now End of the time range.
tz No Etc/UTC Time Zone format in TX format
format No json The desired result format. Supported: json and text.

8. Sumo Logic Confidential
• Sample JSON Response Document
Search API

9. Sumo Logic Confidential
Note:
• This API may be deprecated in the future, in favor of the Search Job API.
• Use the Search Job API where you can.
Search API

10. Sumo Logic Confidential
• Models the asynchronous behavior of a search in the Sumo Logic backend
– Creating a search job returns immediately with the ID for the search job. The ID
can then be used to interact with the search job.
• Provides histogram bucket information
• Asynchronous
• Limitations
– The Search Job API does not have the limitations that the Search API has.
Search Job API

11. Sumo Logic Confidential
• Endpoint: /search/jobs
• Method: POST
• Headers
– Content-Type - application/json
– Accept - application/json
*Time rangevaluescan bespecifiedin ISO8601 formator epoch milliseconds.
Search Job API - Creating a Search Job
Parameter Type Required Description
query String Yes The full search query to be executed.
from String Yes Start of the time range
to String Yes End of the time range
timezone String Yes Time Zone format in TX format

12. Sumo Logic Confidential
• Status Codes
• Response Headers
• Sample JSON Response Document
Search Job API - Creating a Search Job
Status Code Text Description
202 Accepted The search job has been successfully created.
415 Unsupported Media Type Content-Type wasn't set to application/json.
400 Bad Request Generic request error by the client.
Header Value
Location https://api.sumologic.com/api/v1/search/jobs/SEARCH_JOB_ID

13. Sumo Logic Confidential
• Common Error Reasons
– Query is not specified
– Query is invalid
– From/to parameters are not specified
– To is before from time
– From/to values invalid format
– Time zone parameter missing
• If any of the above occur, the response body will contain additional
information.
• Don’t forget to properly escape your query
Search Job API - Creating a Search Job

14. Sumo Logic Confidential
• Endpoint: /search/jobs/SEARCH_JOB_ID
• Method: GET
Search Job API - Checking the status of a Search Job
Sumo Logic Confidential14
Parameter Type Required Description
SEARCH_JOB_ID String Yes The ID of the search job.

15. Sumo Logic Confidential
• Sample JSON Response Document
• Possible States
Search Job API - Checking the status of a Search Job
State Description
NOT STARTED Search job has not been started yet.
GATHERING RESULTS Search job is still gathering more results, however results might already be available.
DONE GATHERING RESULTS Search job is done gathering results; the entire specified time range has been covered.
CANCELLED The search job has been cancelled.

16. Sumo Logic Confidential
• messageCount
– The count of raw log messages
• recordCount
– The count of aggregates
• If your search does not contain any aggregation operators, only the
messageCount is returned.
• pendingErrors, pendingWarnings and histogramBuckets ARE NOT cumulative
– Each request will return the information found since the last request. The client will
need to store these if they must be remembered.
Search Job API - Checking the status of a Search Job

17. Sumo Logic Confidential
• Endpoint:
/search/jobs/SEARCH_JOB_ID/messages?offset=OFFSET&limit=LIMIT
• Method: GET
*The maximumvalue forlimit is 10,000 messages
Search Job API - Paging thru messages
Parameter Required Description
SEARCH_JOB_ID Yes The ID of the search job.
OFFSET Yes Return messages starting at this offset.
LIMIT Yes The number of messages starting at offsetto
return.

18. Sumo Logic Confidential
• Sample JSON Response Document
• The result will contain two lists
– Fieldsis all the fieldsdefined for themessages
– Messagescontainsa list of maps, onemap for each message
Search Job API - Paging thru messages

19. Sumo Logic Confidential
• Endpoint:
/search/jobs/SEARCH_JOB_ID/records?offset=OFFSET&limit=LIMIT
• Method: GET
*The maximumvalue forlimit is 10,000 messages
Search Job API - Paging thru records
Parameter Required Description
SEARCH_JOB_ID Yes The ID of the search job.
OFFSET Yes Return records starting at this offset.
LIMIT Yes The number of records starting at offset to return.

20. Sumo Logic Confidential
• Sample JSON Response Document
• The result will contain two lists
– Fieldsis all the fieldsdefined for therecords
– Recordscontainsa list of maps, onemap for each records
Search Job API - Paging thru records

21. Sumo Logic Confidential
• Endpoint:/search/jobs/SEARCH_JOB_ID
• Method: DELETE
• Although search jobs ultimately timeout, it is best practice to delete a
search job when it is no longer needed.
Search Job API - Deleting a Search Job

22. Sumo Logic Confidential
Search Job API
Demo

23. Sumo Logic Confidential
• Java Client Library
– Available on Maven Central
– https://github.com/SumoLogic/sumo-java-client
• Python Client Library
– https://github.com/SumoLogic/sumologic-python-sdk
Search Libraries

24. Sumo Logic Confidential
• Documentation
– https://github.com/SumoLogic/sumo-api-doc/wiki
– https://support.sumologic.com/hc/en-us/sections/200934938-APIs
• Community Forum
– https://support.sumologic.com/hc/communities/public/topics/200263058-
Sumo-Logic-API
• Email
– api@sumologic.com
API Resources