You can use the Scalyr API to send and retrieve log data directly from Scalyr servers, as well as manage configuration files. It is usually most convenient to use the Scalyr Agent to send log files, and to view logs on the web site. We also provide a Java client library and a command-line tool. But if you'd like to talk directly to the Scalyr servers from a language other than Java, you've come to the right place.
\nAccess to the Scalyr API is via API keys. See API Keys for a discussion of how to create and manage read and write keys for log access and configuration file access. We explain which type of key is required for each method below.
\nAuthentication can happen in two ways:
\n{\"token\":\"{token}\"}?token={token}&...token should be a \"Read Logs\" API key. You can create and manage API keys at https://app.scalyr.com/keys.
\nqueryType should be log.
\nfilter specifies which events to match, using the same syntax as the Expression field in the query UI. To match all events, omit this field or pass an empty string.
\nstartTime and endTime specify the time range to query, using the same syntax as the Start and End fields in the query UI. You can also supply a simple timestamp, measured in seconds, milliseconds, or nanoseconds since 1/1/1970.
\nThe default is to query the last 24 hours. If you specify startTime but not endTime, the query covers 24 hours beginning at the startTime. If you specify endTime but not startTime, the query covers 24 hours ending at the endTime.
\nmaxCount specifies the maximum number of records to return. You may specify a value from 1 to 5000. The default is 100.
\npageMode applies when the number of events matching the query is more than maxCount. Pass head to get the oldest matches in the specified time range, or tail to get the newest. The default is head if you specify a startTime, tail otherwise.
\ncolumns specifies which fields to return for each log message, as a comma-delimited list. Omit this parameter (or pass an empty string) to return all fields.
\ncontinuationToken is used to page through result sets larger than maxCount. Omit this parameter for your first query. You may then repeat the query with the same filter, startTime, endTime, and pageMode to retrieve further matches. Each time, set continuationToken to the value returned by the previous query.
\nWhen using continuationToken, you should set startTime and endTime to absolute values, not relative values such as 4h. If you use relative time values, and the time range drifts so that the continuation token refers to an event that falls outside the new time range, the query will fail.
\npriority specifies the execution priority for this query; defaults to \"low\". Use \"low\" for background operations where a delay of a second or so is acceptable. Low-priority queries have more generous rate limits.
\nAn error is indicated by a response object whose status field does not begin with success. See the API Overview section for details. Otherwise, the response should have the following structure:
\n{\n \"status\": \"success\",\n \"matches\": [\n {\n \"timestamp\": \"1393009097459537089\",\n \"message\": \"hello, world\",\n \"severity\": 3,\n \"session\": \"sess_d5952fdd-eed2-45f1-8106-b2f2af55dabd\",\n \"thread\": \"28\",\n \"attributes\": {\n \"tag\": \"foo\"\n }\n }\n ],\n \"sessions\": {\n \"sess_d5952fdd-eed2-45f1-8106-b2f2af55dabd\": {\n \"serverHost\": \"some.host.name\",\n \"serverIP\": \"1.2.3.4\",\n \"session\": \"sess_d5952fdd-eed2-45f1-8106-b2f2af55dabd\"\n }\n },\n \"cpuUsage\": 12,\n \"continuationToken\": \"L6_ckjI4BgATVPZkxGaUwQ--\"\n}\nmatches lists the events matching the query, up to maxCount. Matches are always given in ascending timestamp order, regardless of whether you are paging forwards or backwards. Each match contains the following fields:
\n(If you specify a columns list, any fields not listed will not appear in the match objects. This applies to built-in fields like timestamp and message, as well as fields in the fields object.)
\nsessions contains an entry for each session mentioned in the matches list. For each session, it lists the fields associated with that session. This includes the hostname and IP address of the server from which you uploaded these events, along with any other fields specified in the sessionInfo parameter of the addEvents API. (For the Scalyr Agent, these are the fields specified in the server_attributes field of the configuration file.)
\ncpuUsage indicates how much time the Scalyr service spent processing this query, in CPU milliseconds. Queries are subject to rate limiting based on CPU usage; see the Query Rate Limiting section.
\ncontinuationToken may be passed to a subsequent API call, to retrieve additional matches. Note that this field may be present in the response even if there are no further matches to retrieve. If you use the continuationToken in a subsequent query, make sure to repeat the same filter, startTime, endTime, and pageMode as the previous query, and set startTime and endTime to absolute values (not relative values such as 4h). If you use relative time values, and the time range drifts so that the continuation token refers to an event that falls outside the new time range, the query will fail.
\n","urlObject":{"protocol":"https","path":["api","query"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"37ccaa67-9ce3-452e-939a-38c00d52ce25"},{"name":"powerQuery","id":"47366b05-af6b-40c6-82ee-92b4f6727e56","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-read-token}}\",\n \"query\": \"serverHost = * | columns serverHost, timestamp | limit 10 \",\n \"startTime\": \"4h\",\n \"endTime\": \"0h\",\n // \"priority\": \"...\"\n}"},"url":"https://app.scalyr.com/api/powerQuery","description":"pq
\n","urlObject":{"protocol":"https","path":["api","powerQuery"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"47366b05-af6b-40c6-82ee-92b4f6727e56"},{"name":"timeseriesQuery","id":"2f8a9882-8c06-433e-8e6a-033fbd6522fd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-read-token}}\",\n \"queries\": [\n {\n \"filter\": \"serverHost = *\",\n \"function\": \"count\",\n \"startTime\": \"4h\",\n \"endTime\": \"0h\",\n \"buckets\": 4 //4 buckets in a 4 hour time range is 1bucket/hr\n },\n\n ]\n}"},"url":"https://www.scalyr.com/api/timeseriesQuery","urlObject":{"protocol":"https","path":["api","timeseriesQuery"],"host":["www","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"2f8a9882-8c06-433e-8e6a-033fbd6522fd"},{"name":"facetQuery","id":"d302916f-383b-458d-92e6-f0b3bae92999","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-read-token}}\",\n \"queryType\": \"facet\",\n \"filter\": \"serverHost = *\",\n \"field\": \"serverHost\",\n \"maxCount\": 20,\n \"startTime\": \"4h\",\n \"endTime\": \"0h\",\n \"priority\": \"high\"\n}"},"url":"https://app.scalyr.com/api/facetQuery","urlObject":{"protocol":"https","path":["api","facetQuery"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"d302916f-383b-458d-92e6-f0b3bae92999"}],"id":"c6aa96a4-4d91-4ae7-ab19-843b5b2667d2","description":"You can use the Scalyr API to query data in multiple ways. Use the Query endpoint to pull raw data, the powerQuery endpoint for more control or to perform on-the-fly queries, or the timeseriesQuery to create or request timeseries metrics from the timeseries database.
\n","_postman_id":"c6aa96a4-4d91-4ae7-ab19-843b5b2667d2"},{"name":"Write Data","item":[{"name":"addEvents","event":[{"listen":"prerequest","script":{"id":"78a91a0a-1a58-4e28-880d-4880a82b4a51","exec":["var moment = require('moment');","var ts = moment().valueOf();","pm.environment.set('currentdate', ts*1000000);","pm.environment.set('currentdate1', ts*1000000);","pm.environment.set('currentdate2', ts*1000000);","pm.environment.set('currentdate3', ts*1000000);","pm.environment.set('currentdate4', ts*1000000);","pm.environment.set('currentdate5', ts*1000000);","pm.environment.set('currentdate6', ts*1000000);","pm.environment.set('currentdate7', ts*1000000);","pm.environment.set('currentdate8', ts*1000000);","pm.environment.set('currentdate9', ts*1000000);","pm.environment.set('currentdate10', ts*1000000);","pm.environment.set('currentdate11', ts*1000000);","pm.environment.set('currentdate12', ts*1000000);","","pm.environment.set(\"random_number\", _.random(1, 500))","",""],"type":"text/javascript"}}],"id":"5ba55d7a-bcda-4c3d-9930-d9710a38aaae","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n\t\"token\":\"{{scalyr-write-token}}\",\n\t\"session\": \"test_session_3abcsdfsdfsd\",\n \n\t\"sessionInfo\": {\n\t\t\"serverHost\": \"newServer1\",\n\t\t\"logfile\": \"/var/log/log.txt\",\n \"parser\": \"json\"\n },\n\t\t\"events\": [\n\t\t{\n\t\t\t\t\"ts\": \"{{currentdate}}\", \n\t\t\t\t\"attrs\": {\n\t\t\t\t\t\"message\": \"{\\\"hello\\\":\\\"world\\\", \\\"event\\\": 1}\"\n\n\t\t\t}\n\t\t},\n {\n\t\t\t\t\"ts\": \"{{currentdate}}\", \n\t\t\t\t\"attrs\": {\n\t\t\t\t\t\"message\": \"{\\\"hello\\\":\\\"world\\\", \\\"event\\\": 2}\"\n\n\t\t\t}\n\t\t}\n \n\t]\n}","options":{"raw":{"language":"json"}}},"url":"https://app.scalyr.com/api/addEvents","description":"add events endpoinnt
\n","urlObject":{"protocol":"https","path":["api","addEvents"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"5ba55d7a-bcda-4c3d-9930-d9710a38aaae"},{"name":"uploadLogs","id":"b1e4779a-7282-44c2-9978-301ba75de391","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"This is a log"},"url":"https://app.scalyr.com/api/uploadLogs?token={{scalyr-read-token}}","urlObject":{"protocol":"https","path":["api","uploadLogs"],"host":["app","scalyr","com"],"query":[{"key":"token","value":"{{scalyr-read-token}}"}],"variable":[]}},"response":[],"_postman_id":"b1e4779a-7282-44c2-9978-301ba75de391"}],"id":"d9f4e6b5-9359-4677-84cb-9fae9b7b2dea","_postman_id":"d9f4e6b5-9359-4677-84cb-9fae9b7b2dea","description":""},{"name":"Manage Users","item":[{"name":"listUsers","id":"d0454afc-67d4-4f93-87ca-32b14602651e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-read-token}}\"\n}"},"url":"https://app.scalyr.com/api/listUsers","urlObject":{"protocol":"https","path":["api","listUsers"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"d0454afc-67d4-4f93-87ca-32b14602651e"},{"name":"inviteUser","id":"8457d126-7e35-40dc-bea8-8138b95e685a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"emailAddress\": \"xxx@xxx.xxx\",\n \"permission\": \"full\",\n \"allowedSearch\": \"\",\n \"allowedDashboards\": [],\n \"groups\": []\n}"},"url":"https://app.scalyr.com/api/inviteUser","description":"pq
\n","urlObject":{"protocol":"https","path":["api","inviteUser"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"8457d126-7e35-40dc-bea8-8138b95e685a"},{"name":"editUserPermissions","id":"b624f305-02cd-499b-9e0a-3f7628fad92e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"emailAddress\": \"xxx@xxx.xxx\",\n \"permission\": \"full\",\n \"allowedSearch\": \"\",\n \"allowedDashboards\": [],\n \"groups\": []\n}"},"url":"https://app.scalyr.com/api/editUserPermissions","description":"pq
\n","urlObject":{"protocol":"https","path":["api","editUserPermissions"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"b624f305-02cd-499b-9e0a-3f7628fad92e"},{"name":"revokeAccess","id":"3ab15f76-18c3-441a-8cbe-60553e59c487","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"emailAddress\": \"xxx@xxx.xxx\"\n}"},"url":"https://app.scalyr.com/api/revokeAccess","description":"pq
\n","urlObject":{"protocol":"https","path":["api","revokeAccess"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"3ab15f76-18c3-441a-8cbe-60553e59c487"}],"id":"f7d25b76-9fc3-4157-8407-4743a1a1ed09","_postman_id":"f7d25b76-9fc3-4157-8407-4743a1a1ed09","description":""},{"name":"Manage Groups","item":[{"name":"addGroup","id":"db9c013a-f64d-479d-ae28-bc39b0008fd8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"name\": \"Group Name\",\n \"permission\": \"limited\",\n \"allowedSearch\": \"\",\n \"allowedDashboards\": []\n}"},"url":"https://app.scalyr.com/api/addGroup","description":"pq
\n","urlObject":{"protocol":"https","path":["api","addGroup"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"db9c013a-f64d-479d-ae28-bc39b0008fd8"},{"name":"editGroupPermission","id":"4d962c81-e905-4d8d-9860-08046f6b7dc4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"name\": \"Group Name\",\n \"permission\": \"limited\",\n \"allowedSearch\": \"\",\n \"allowedDashboards\": []\n}"},"url":"https://app.scalyr.com/api/editGroupPermissions","description":"pq
\n","urlObject":{"protocol":"https","path":["api","editGroupPermissions"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"4d962c81-e905-4d8d-9860-08046f6b7dc4"},{"name":"removeGroup","id":"6f2be988-26d1-4ec2-91c7-b69b017e05fa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"name\": \"Group Name\"\n} "},"url":"https://app.scalyr.com/api/removeGroup","description":"pq
\n","urlObject":{"protocol":"https","path":["api","removeGroup"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"6f2be988-26d1-4ec2-91c7-b69b017e05fa"},{"name":"listGroups","id":"bde1b1ee-06b6-4511-9699-6929d2e95d7e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-read-token}}\",\n \"groupName\": \"Group Name\",\n \"userEmails\": [\"alice@example.com\", \"bob@example.com\"]\n}"},"url":"https://app.scalyr.com/api/listGroups","description":"pq
\n","urlObject":{"protocol":"https","path":["api","listGroups"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"bde1b1ee-06b6-4511-9699-6929d2e95d7e"},{"name":"listUsersInGroup","id":"6aaf82e4-4409-4320-b7ce-0b27df1cdfee","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-read-token}}\",\n \"groupName\": \"Group Name\",\n}"},"url":"https://app.scalyr.com/api/listUsersInGroup","description":"pq
\n","urlObject":{"protocol":"https","path":["api","listUsersInGroup"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"6aaf82e4-4409-4320-b7ce-0b27df1cdfee"},{"name":"removeUsersFromGroup","id":"3728c3b2-d96f-455a-8356-a14c18329231","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"groupName\": \"Group Name\",\n \"userEmails\": [\"alice@example.com\", \"bob@example.com\"]\n}"},"url":"https://app.scalyr.com/api/removeUsersFromGroup","description":"pq
\n","urlObject":{"protocol":"https","path":["api","removeUsersFromGroup"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"3728c3b2-d96f-455a-8356-a14c18329231"},{"name":"addUsersToGroup","id":"5ae4692c-5eea-44cd-8012-9e010664b329","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"groupName\": \"Group Name\",\n \"userEmails\": [\"alice@example.com\", \"bob@example.com\"]\n}"},"url":"https://app.scalyr.com/api/addUsersToGroup","description":"pq
\n","urlObject":{"protocol":"https","path":["api","addUsersToGroup"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"5ae4692c-5eea-44cd-8012-9e010664b329"},{"name":"listUsersInGroup","id":"3649d314-28e7-47d5-b4f6-712c98dba2e8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-write-token}}\",\n \"groupName\": \"Group Name\",\n}"},"url":"https://app.scalyr.com/api/listUsersInGroup","description":"pq
\n","urlObject":{"protocol":"https","path":["api","listUsersInGroup"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"3649d314-28e7-47d5-b4f6-712c98dba2e8"}],"id":"c89ac42d-c297-416e-b8cd-fa746803c8c1","_postman_id":"c89ac42d-c297-416e-b8cd-fa746803c8c1","description":""},{"name":"Manage Files","item":[{"name":"getFile","id":"b8e922a0-3ba5-450b-a1fe-106ab24aa48f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"\n{\n \"token\": \"{{scalyr-config-read-token}}\",\n \"path\": \"/scalyr/logs\", //get main user config file\n \"expectedVersion\": 1, // optional\n \"prettyprint\": false // optional\n}"},"url":"https://www.scalyr.com/getFile","description":"This method is used to retrieve a configuration file. You can also use this method to block until the file is changed.
\n","urlObject":{"protocol":"https","path":["getFile"],"host":["www","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"b8e922a0-3ba5-450b-a1fe-106ab24aa48f"},{"name":"listFiles","id":"5f55e277-e3c0-4e9d-81cb-b44e4d823bf3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-read-token}}\"\n}"},"url":"https://app.scalyr.com/api/listFiles","urlObject":{"protocol":"https","path":["api","listFiles"],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"5f55e277-e3c0-4e9d-81cb-b44e4d823bf3"},{"name":"putFile","id":"12797f76-60b6-4954-b0a3-445ef875eb93","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"{{scalyr-config-read-token}}\",\n \"path\": \"/newFile\",\n \"content\": \"{\\\"hello\\\":\\\"world\\\"}\",\n \"prettyprint\": false, // optional\n \"expectedVersion\": 3 // optional\n}"},"url":"https://www.scalyr.com/getFile","description":"This method is used to retrieve a configuration file. You can also use this method to block until the file is changed.
\n","urlObject":{"protocol":"https","path":["getFile"],"host":["www","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"12797f76-60b6-4954-b0a3-445ef875eb93"}],"id":"646c6d69-9d65-4f5f-aec9-25dcb1dfb1bb","_postman_id":"646c6d69-9d65-4f5f-aec9-25dcb1dfb1bb","description":""},{"name":"Manage Teams","item":[{"name":"Create Team","id":"4b2d662d-b24c-4f89-ab65-8ff48385134c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{ \n token: \"{{scalyr-config-write-token}}\", // A \"write configuration\" key for the main account \n emailAddress: \"xxx@xxx.xxx\" // Email address of the newteam account \n} "},"url":"https://app.scalyr.com/api/createTeamAccount ","urlObject":{"protocol":"https","path":["api","createTeamAccount "],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"4b2d662d-b24c-4f89-ab65-8ff48385134c"},{"name":"List Teams","id":"57afb623-3532-46d0-bfe3-1da1c484435e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{ \n token: \"{{scalyr-config-write-token}}\", // A \"write configuration\" key for the main account \n emailAddress: \"xxx@xxx.xxx\" // Email address of the newteam account \n} "},"url":"https://app.scalyr.com/api/createTeamAccount ","urlObject":{"protocol":"https","path":["api","createTeamAccount "],"host":["app","scalyr","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"57afb623-3532-46d0-bfe3-1da1c484435e"}],"id":"91fe9f89-63df-4f21-8e1e-cb74b8e7f3cf","_postman_id":"91fe9f89-63df-4f21-8e1e-cb74b8e7f3cf","description":""}],"variable":[{"key":"scalyr-key","value":"0P67u1yoYqTsMF0gchc9braNxSHfWCgc0wM5ffhWZYT0-"}]}