Working with the Aggregation task API

[ 1 Overview ] [ 2 Endpoints and methods ]

Overview

Check the list of available endpoints and methods in the Aggregation task API:

Endpoints and methods	Description

Endpoints and methods	Description
status:GET `/aggrtasks/{domain}`^{see below}	Get information about all the aggregation tasks in a domain.
status:GET `/aggrtasks/{domain}/{aggrId}`^{see below}	Get information about a specific aggregation task.
status:GET `/aggrtasks/{domain}/{aggrId}/measures`^{see below}	Get the measures of an aggregation task.
status:POST `/aggrtasks/{domain}` ^{see below}	Create a new aggregation task.
status:PUT `/aggrtasks/{domain}/{aggrId}` ^{see below}	Update an aggregation task.
status:PUT `/aggrtasks/{domain}/{aggrId}/stop` ^{see below}	Stop an aggregation task.
status:PUT `/aggrtasks/{domain}/{aggrId}/start` ^{see below}	Start a task and add aggregated data from a specific date.
status:PUT `/aggrtasks/{domain}/{aggrId}/resume` ^{see below}	Resume a stopped aggregation task.
status:DELETe `/aggrtasks/{domain}/{aggrId}` ^{see below}	Delete an aggregation task.

Endpoints and methods

GET `/aggrtasks/{domain}`

Get information about all the aggregation tasks in a domain.

To perform this request, your Devo user must have at least the Aggregation tasks (view) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation tasks you want to get information about.

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter	Type	Description

Parameter	Type	Description
`skipCache`	`boolean`	If it is `true`, skips the cache that contains the status of the aggregation tasks and force the system to tell you where to find them. Default value is `false`.
`status`	`string`	Execution status of the aggregation tasks. Available values are: `RUNNING` `STOPPED` `DELETED` `ERROR` `PARTIAL_STOPPED` `PENDING_CREATE` `PENDING_START` `PENDING_STOP` `PENDING_UPDATE` `PENDING_REBUILD` `PENDING_DELETE` `PENDING_RESUME` `PENDING_EXTEND`
`id`	`string`	If you want to get details about a specific aggregation task only, enter its ID here. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.
`fromDate`	`integer`	Timestamp from when the aggregation tasks to be returned were created. Format is a timestamp in milliseconds, for example `1652400000000`
`name`	`string`	If you want to get details about a specific aggregation task only, you can enter its name.
`ownerEmail`	`string`	Email of the aggregation tasks' owner.
`negated`	`boolean`	Set this to `true` to negate all other parameters. Default value is `false`.

Example

Find below a request example in cURL language. In this case, we are requesting all the aggregation tasks with status STOPPED created in the given domain. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain?status=STOPPED"

Code	Description

Code	Description
200	Successful response. List of aggregation tasks retrieved. [ { "id": "cc_myDomain:nQEbd480", "name": "test1", "delay": 0, "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "jobs": [ { "grain": "1m", "status": "STOPPED", "from": 1652400000000, "to": 1652432340000 }, { "grain": "5m", "status": "STOPPED", "from": 1652400000000, "to": 1652400000000 }, { "grain": "1h", "status": "STOPPED", "from": 1652400000000, "to": 1652400000000 } ], "creationDate": 1652432342000, "updateDate": 1652432342000, "status": "STOPPED", "statusData": "INCOMPLETE", "fromDate": 1652400000000 }, { "id": "cc_myDomain:oYckc691", "name": "test2", "delay": 0, "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "jobs": [ { "grain": "1m", "status": "STOPPED", "from": 1652400000000, "to": 1652436480000 }, { "grain": "5m", "status": "STOPPED", "from": 1652400000000, "to": 1652436300000 }, { "grain": "1h", "status": "STOPPED", "from": 1652400000000, "to": 1652436000000 } ], "creationDate": 1652436468000, "updateDate": 1652436468000, "status": "STOPPED", "statusData": "INCOMPLETE", "fromDate": 1652400000000 } ]
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

GET `/aggrtasks/{domain}/{aggrId}`

Get information about a specific aggregation task in a given domain.

To perform this request, your Devo user must have at least the Aggregation tasks (view) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation task you want to get information about.
`aggrId` ^required	`string`	Enter the ID of the aggregation task you want to get information about. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter	Type	Description

Parameter

Type

Description

skipCache

boolean

If it is true, skips the cache that contains the status of the aggregation task and force the system to tell you where to find it.

Default value is false.

Example

Find below a request example in cURL language. In this case, we are requesting details about the aggregation task with ID cc_myDomain:abcDE123 created in the domain called myDomain. Also, we want to skip the cache about its status. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123?skipCache=true"

Code	Description

Code	Description
200	Successful response. aggregation task details retrieved. { "id": "cc_myDomain:abcDE123", "name": "Test", "table": "demo.ecommerce.data`1234`.`345`", "wheres": [ "eq(client, \"myDomain\")" ], "delay": 0, "query": { "linq": "from demo.ecommerce.data`1234`.`345` where eq(client, \"myDomain\") group every 60000 by level, type, message, client" }, "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "jobs": [ { "grain": "1m", "status": "STOPPED", "from": 1652400000000, "to": 1652432040000 }, { "grain": "5m", "status": "STOPPED", "from": 1652400000000, "to": 1652400000000 }, { "grain": "1h", "status": "STOPPED", "from": 1652400000000, "to": 1652400000000 } ], "creationDate": 1652432055000, "updateDate": 1652432055000, "status": "STOPPED", "statusData": "INCOMPLETE", "fromDate": 1652400000000 }
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

GET `/aggrtasks/{domain}/{aggrId}/measures`

Get the measures of an aggregation task.

To perform this request, your Devo user must have at least the Aggregation tasks (view) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Parameter

Parameter	Type	Parameter
`domain` ^required	`string`	Enter the domain of the aggregation task you want to get information about.
`aggrId` ^required	`string`	Enter the ID of the aggregation task you want to get information about. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Example

Find below a request example in cURL language. In this case, we are requesting the measures of the aggregation task with ID cc_myDomain:abcDE123 created in the domain called myDomain. Also, we want to skip the cache about its status. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123/measures"

Code	Description

Code	Description
200	Successful response. In this example, the task is calculating three aggregations: `count()` `avg(responseTime)` `sum(responseTime)` `{ "responseTime": [ "avg", "sum" ], "count": [] }`
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

POST `/aggrtasks/{domain}`

Create a new aggregation task.

To perform this request, your Devo user must have at least the Aggregation tasks (manage) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain where you want to create the aggregation task.

Request body

The request JSON body must include an object with the following key-value pairs:

Parameter	Type	Description

Parameter	Type	Description
`name` ^required	`string`	Aggregation task's name, which must be unique in the domain.
`query` ^required	`object`	An object that contains three parameters: `LINQ` - Base query of the aggregation task, written in LINQ syntax. `timezone` - Timezone of the aggregation task query, in the following format: `Europe/Madrid` `locale` - Locale of the aggregation task query, in the following format: `en`
`fromDate` ^required	`string`	Date from which the aggregation task searches to calculate the aggregated data. Valid format is `dd/mm/yyyy`
`description`	`string`	Brief description of the aggregation task.
`delay`	`integer`	Maximum acceptable time difference between the current time and the last event displayed. You can indicate it in seconds (`1s`), minutes (`1m`), hours (`1h`) and days (`1d`). Default value is `0`
`minGrain`	`string`	Minimum granularity of the aggregation task. Available values are: `AUTO` - Calculate best aggregation according to the given query. `1m` - Aggregate every minute. `5m` - Aggregate every 5 minutes. `30m` - Aggregate every 30 minutes.

Example

Find below a request example in cURL language. In this case, we are creating a new aggregation task in the domain called myDomain. Learn how to authorize your request in this article.

curl --location -g 'https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "MyNewAggTask",
    "description": "This is a test aggregation task",
    "fromDate": "06/02/2023",
    "minGrain": "30m",
    "query": {
        "timeZone": "Europe/Madrid",
        "locale": "es",
        "linq": "from siem.logtrust.web.activity group every 5m by username every 5m select avg(responseTime) as responseTime"
    }    
}'

Code	Description

Code	Description
200	Successful response. Aggregation task created. { "id": "cc_myDomain:abcDE123", "name": "MyNewAggTask", "table": "siem.logtrust.web.activity", "wheres": [ "eq(client, \"myDomain\")" ], "delay": 0, "query": { "linq": "from siem.logtrust.web.activity where eq(client, \"integrations_factory\") group every 60000 by username, client select sumf(responseTime) as responseTime_sumf", "timeZone": "Europe/Madrid", "locale": "es" }, "description": "my new aggregation task", "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "creationDate": 1677087818714, "updateDate": 1677087818714, "status": "PENDING_CREATE", "statusData": null, "fromDate": 0 }
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

PUT `/aggrtasks/{domain}/{aggrId}`

Update a specific aggregation task.

To perform this request, your Devo user must have at least the Aggregation tasks (manage) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation task that you want to update.
`aggrId` ^required	`string`	Enter the ID of the aggregation task that you want to update. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Request body

The request JSON body must include an object with the following key-value pairs:

Parameter	Type	Description

Parameter	Type	Description
`query`	`object`	An object that contains three parameters: `LINQ` - Base query of the aggregation task, written in LINQ syntax. `timezone` - Timezone of the aggregation task query, in the following format: `Europe/Madrid` `locale` - Locale of the aggregation task query, in the following format: `en`
`description`	`string`	Brief description of the aggregation task.
`delay`	`integer`	Maximum acceptable time difference between the current time and the last event displayed. You can indicate it in seconds (`1s`), minutes (`1m`), hours (`1h`) and days (`1d`). Default value is `0`
`minGrain`	`string`	Minimum granularity of the aggregation task. Available values are: `AUTO` - Calculate best aggregation according to the given query. `1m` - Aggregate every minute. `5m` - Aggregate every 5 minutes. `30m` - Aggregate every 30 minutes.

Example

Find below a request example in cURL language. In this case, we are updating an aggregation task with ID cc_myDomain:abcDE123 in the domain called myDomain. Learn how to authorize your request in this article.

curl --location --request PUT 'https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "description": "Aggregation task updated",
    "minGrain": "5m",
    "query": {
        "timeZone": "Europe/Madrid",
        "locale": "es",
        "linq": "from siem.logtrust.web.activity group every 10m by username every 5m select avg(responseTime) as responseTime"
    }    
}'

Code	Description

Code	Description
200	Aggregation task successfully updated. { "id": "cc_myDomain:abcDE123", "name": "MyNewAggTask", "table": "siem.logtrust.web.activity", "wheres": [ "eq(client, \"myDomain\")" ], "delay": 0, "query": { "linq": "from siem.logtrust.web.activity where eq(client, \"integrations_factory\") group every 60000 by username, client select sumf(responseTime) as responseTime_sumf", "timeZone": "Europe/Madrid", "locale": "es" }, "description": "Aggregation task updated", "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "creationDate": 1677087818714, "updateDate": 1677087818714, "status": "PENDING_CREATE", "statusData": null, "fromDate": 0 }
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

PUT `/aggrtasks/{domain}/{aggrId}/stop`

Stop an aggregation task.

To perform this request, your Devo user must have at least the Aggregation tasks (manage) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation task that you want to stop.
`aggrId` ^required	`string`	Enter the ID of the aggregation task that you want to stop. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Example

Find below a request example in cURL language. In this case, we want to stop the aggregation task with ID cc_myDomain:abcDE123 in the domain called myDomain. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123/stop"

Code	Description

Code	Description
200	Aggregation task stopped. `true`
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

PUT `/aggrtasks/{domain}/{aggrId}/start`

Start a new task and add aggregated data from a specific date.

To perform this request, your Devo user must have at least the Aggregation tasks (manage) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain where you want the aggregation task to be.
`aggrId` ^required	`string`	Enter the ID of the aggregation task that you want to start. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter	Type	Description

Parameter	Type	Description
`from` ^required	`integer`	Timestamp from when the aggregation task will be started. Format is a timestamp in milliseconds, for example `1652400000000`

Example

Find below a request example in cURL language. In this case, we want to start the aggregation task with ID cc_myDomain:abcDE123 in the domain called myDomain from a specific date indicated in the timestamp added to the URL. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123/start?from=1652400000000"

Code	Description

Code	Description
200	Aggregation task started. `true`
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

PUT `/aggrtasks/{domain}/{aggrId}/resume`

Resume an aggregation task from the date it was stopped.

To perform this request, your Devo user must have at least the Aggregation tasks (manage) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation task that you want to resume.
`aggrId` ^required	`string`	Enter the ID of the aggregation task that you want to resume. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Example

Find below a request example in cURL language. In this case, we want to resume the aggregation task with ID cc_myDomain:abcDE123 in the domain called myDomain. Also, we want to skip the cache about its status. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123/resume"

Code	Description

Code	Description
200	Aggregation task resumed. `true`
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

DELETE `/aggrtasks/{domain}/{aggrId}`

Delete an aggregation task. This will permanently remove all the tasks and associated metadata.

To perform this request, your Devo user must have at least the Aggregation tasks (manage) permission assigned. Learn more about roles and permissions in Role permissions.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation task that you want to delete.
`aggrId` ^required	`string`	Enter the ID of the aggregation task that you want to delete. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Find below a request example in cURL language. In this case, we want to delete the aggregation task with ID cc_myDomain:abcDE123 in the domain called myDomain. Also, we want to skip the cache about its status. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X DELETE "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123"

Code	Description

Code	Description
200	Aggregation task deleted. `true`
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

Devo latest

Working with the Aggregation task API

Overview

Endpoints and methods

GET `/aggrtasks/{domain}`

Path parameters

Query string parameters

Example

GET `/aggrtasks/{domain}/{aggrId}`

Path parameters

Query string parameters

Example

GET `/aggrtasks/{domain}/{aggrId}/measures`

Path parameters

Example

POST `/aggrtasks/{domain}`

Path parameters

Request body

Example

PUT `/aggrtasks/{domain}/{aggrId}`

Path parameters

Request body

Example

PUT `/aggrtasks/{domain}/{aggrId}/stop`

Path parameters

Example

PUT `/aggrtasks/{domain}/{aggrId}/start`

Path parameters

Query string parameters

Example

PUT `/aggrtasks/{domain}/{aggrId}/resume`

Path parameters

Example

DELETE `/aggrtasks/{domain}/{aggrId}`

Path parameters

Related content

Working with the Aggregation task API

Overview

Endpoints and methods

GET /aggrtasks/{domain}

Path parameters

Query string parameters

Example

GET /aggrtasks/{domain}/{aggrId}

Path parameters

Query string parameters

Example

GET /aggrtasks/{domain}/{aggrId}/measures

Path parameters

Example

POST /aggrtasks/{domain}

Path parameters

Request body

Example

PUT /aggrtasks/{domain}/{aggrId}

Path parameters

Request body

Example

PUT /aggrtasks/{domain}/{aggrId}/stop

Path parameters

Example

PUT /aggrtasks/{domain}/{aggrId}/start

Path parameters

Query string parameters

Example

PUT /aggrtasks/{domain}/{aggrId}/resume

Path parameters

Example

DELETE /aggrtasks/{domain}/{aggrId}

Path parameters

Related content

GET `/aggrtasks/{domain}`

GET `/aggrtasks/{domain}/{aggrId}`

GET `/aggrtasks/{domain}/{aggrId}/measures`

POST `/aggrtasks/{domain}`

PUT `/aggrtasks/{domain}/{aggrId}`

PUT `/aggrtasks/{domain}/{aggrId}/stop`

PUT `/aggrtasks/{domain}/{aggrId}/start`

PUT `/aggrtasks/{domain}/{aggrId}/resume`

DELETE `/aggrtasks/{domain}/{aggrId}`