Skip to main content
Sumo Logic

Collector API Methods and Examples

The Collector Management API allows you to create, update, and delete Collectors and Sources from an HTTP endpoint. This topic describes the Collector API methods and lists the error codes. 

See the following topics for additional information:

Response fields 

The following table lists the API response fields for installed and hosted Collectors.

Parameter Type Required? Default Description Access
name String Yes   Name of the Collector Modifiable
id Long Yes   Identifier Not modifiable
description String No Null Description of the Collector. Modifiable
category String No Null The Category of the Collector, used as metadata when searching data. Modifiable
hostName String No Null Host name of the Collector. The hostname can be a maximum of 128 characters. Modifiable
timeZone String No Null Time zone of the Collector. Modifiable
ephemeral Boolean Yes   If a Collector is flagged as ephemeral, it is deleted after 12 hours of inactivity. Modifiable
targetCpu Long No Null If specified, when the CPU utilization exceeds this threshold, the Collector will slow down its ingestion of data to lower its resource utilization. Currently only Local and Remote File Sources are supported. Learn more. Modifiable
collectorType String     The Collector type: Installable or Hosted Not modifiable
collectorVersion String Yes   Version of the Collector software installed. Transient
alive Boolean Yes   Whether the Collector is currently seen as alive by the service. Transient
lastSeenAlive Long No   The last time the Sumo Logic service received an active heartbeat from the Collector, specified as milliseconds since epoch. Transient
cutoffTimestamp Long No 0 (collects all data) Only collect data from files with a modified date more recent than this timestamp, specified as milliseconds since epoch Modifiable
cutoffRelativeTime String No   Can be specified instead of cutoffTimestamp to provide a relative offset with respect to the current time. Example: use "-1h""-1d", or "-1w" to collect data that's less than one hour, one day, or one week old, respectively.   
sourceSyncMode String No UI For Installable Collectors, whether the Collector is using local source configuration management (viaJSON file), or cloud management (via UI) Not modifiable

The following table lists additional response fields for installed Collectors only.

Parameter Type Required? Description Access
osName String Yes Name of OS that Collector is installed on. Not modifiable
osVersion String Yes Version of the OS that Collector is installed on. Not modifiable
osArch   Yes Architecture of the OS that Collector is installed on. Not modifiable
osTime Long Yes Time that the Collector has been running, in milliseconds. Not modifiable

GET methods 

List Collectors  

Get a list of Collectors with optional limit and offset.

Method: GET Path: /collectors

Parameter Type Required? Default Description
limit Integer No 1000 Max number of Collectors to return.
offset Integer No 0 Offset into the list of Collectors.
Example 

In this example, setting limit=10 limits the responses to 10.

Request:

curl -u 'accessid:accesskey' -X GET https://api.sumologic.com/api/v1/collectors?limit=10

Response:

{  
   "collectors":[  
      {  
         "id":2,
         "name":"OtherCollector",
         "collectorType":"Installable",
         "alive":true,
         "links":[  
            {  
               "rel":"sources",
               "href":"/v1/collectors/2/sources"
            }
         ],
         "collectorVersion":"19.33-28",
         "ephemeral":false,
         "description":"Local Windows Collection",
         "osName":"Windows 7",
         "osArch":"amd64",
         "osVersion":"6.1",
         "category":"local"
      },
      ...
   ]
}

Get Collector by ID 

Get the Collector with the specified ID.

Method: GET Path: /collectors/[id]

Parameter Type Required? Default Description
id Integer Yes NA ID of the Collector.
Example 

This example gets the Collector with ID 25.

Request:

curl -u 'accessid:accesskey' -X GET https://api.sumologic.com/api/v1/collectors/25

Response:

{
  "collector":{
    "id":25,
    "name":"dev-host-1",
    "timeZone":"UTC",
    "ephemeral":false,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162-12",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471553524302,
    "alive":true
  }
}

POST methods

Create Hosted Collector

Create a new Hosted Collector. See the "Response Fields" table above for required fields for the request JSON file. Note that "id" field should be omitted when creating a new Hosted Collector.

Method: POST Path: /collectors

Example

This example creates a new Hosted Collector using the parameters in the JSON file.

Request:

curl -u 'accessid:accesskey' -X POST -H "Content-Type: application/json" -T hosted_collector.json https://api.sumologic.com/api/v1/collectors

Request JSON (hosted_collector.json):

{
  "collector":{
    "collectorType":"Hosted",
    "name":"My Hosted Collector",
    "description":"An example Hosted Collector",
    "category":"HTTP Collection"
  }
}

Response:

{
   "collector": {
      "id": 100772723,
      "name": "My Hosted Collector",
      "description": "An example Hosted Collector",
      "category": "HTTP Collection",
      "timeZone": "UTC",
      "links": [
         {
            "rel": "sources",
            "href": "/v1/collectors/100772723/sources"
         }
      ],
      "collectorType": "Hosted",
      "collectorVersion": "",
      "lastSeenAlive": 1476818195411,
      "alive": true
   }
}

PUT methods 

Update a Collector 

Update an existing collector. See the table of parameters in 'Response parameters' section of this topic. The JSON request file must specify values for all required fields. Not modifiable fields must match their current values in the system. This is in accordance with HTTP 1.1 RFC-2616 Section 9.6. 

Updating a Collector also requires the "If-Match" header to be specified with the "ETag" provided in the headers of a previous GET request.

Method: PUT Path: /collectors/[id]

Parameter Type Required? Default Description
id Integer Yes NA ID of the Collector.
Example 

This example changes the Collector with ID 15 to have attribute "ephemeral" = true.

First, use a GET request with -v flag to obtain the "ETag" header value.

Initial GET Request:

curl -v -u 'accessid:accesskey' -X GET https://api.sumologic.com/api/v1/collectors/15

Initial GET Response:

< HTTP/1.1 200 OK
< ETag: "f58d12c6986f80d6ca25ed8a3943daa9"
...
{
  "collector":{
    "id":15,
    "name":"dev-host-1",
    "timeZone":"UTC",
    "ephemeral":false,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471553974526,
    "alive":true
  }
* Connection #0 to host api.sumologic.com left intact

Next, modify the Collector's JSON attributes as needed (in this example, setting "ephemeral" to "true"), and use a PUT request, passing the "ETag" value obtained above with the "If-Match" header.

Request:

curl -u 'accessid:accesskey' -X PUT -H "Content-Type: application/json" -H "If-Match: \"f58d12c6986f80d6ca25ed8a3943daa9\"" -T updated_collector.json https://api.sumologic.net/api/v1/collectors/15

Request JSON (updated_collector.json):

{
 "collector":{
    "id":15,
    "name":"dev-host-1",
    "timeZone":"UTC",
    "ephemeral":true,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471553974526,
    "alive":true
  }
}

Response:

{
  "collector":{
    "id":15,
    "name":"dev-host-1",
    "timeZone":"UTC",
    "ephemeral":true,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471554424736,
    "alive":true
  }
}

DELETE methods 

Delete an existing Collector. See the table of parameters in the 'GET methods' section of this topic.

Method: DELETE Path: /collectors/[id]

Parameter Type Required? Default Description
id Integer Yes NA ID of the Collector.

This example deletes the Collector with ID 15.

Request:

curl -u 'accessid:accesskey' -X DELETE https://api.sumologic.com/api/v1/collectors/15

Response: There will be no response body, only a 200 OK response code.

Error Codes and Messages  

Code Message
BadRequestCollectorId Request body contains an invalid Collector ID.
CannotModifyCollector User is not authorized to modify the specified Collector.
CollectorDescriptionTooLong Maximum description length is 1024 characters.
CollectorNameTooLong Maximum name length is 128 characters.
createValidationError The specified ID is invalid.
DuplicateResourceName A resource with the same name already exists.
InvalidCollector The specified Collector ID is invalid.
InvalidCollectorType Invalid Collector type for the requested operation.