Cycles

Some machines within MAT perform cycles. For each cycle, certain information is recorded, such as the cycle ID, its duration, and the aggregators present on the machine at the time of the cycle. Through the API, it is possible to download the data related to these cycles.

POST Method

The functionalities of this endpoint allow retrieving data related to cycles within a specified time interval. The resample operation enables you to either obtain the full list of cycles or simply the number of cycles that occurred during the interval.

Request

HTTP
POST https://{BASE_URL}/apis/cycles/<assetId>

where:

• assetId : machine id to be considered.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

• subAssetId : sub-machine id to be considered. This field can be omitted if the considered asset is not multi-machine.

Body

JSON
{
    "from": "2025-04-01T22:00:00.000Z",
    "to": "2025-04-02T22:00:00.000Z",
    "resampleBy": "1h",
    "filterBy": None,
    "limit": None,
    "calendar": 0
}

In the request body, the following parameters can be specified:

• from: the start time from which to begin downloading the data, expressed in UTC in the format "YYYY-MM-DDThh:mm:ss.sssZ" (ISO 8601 standard);

• to: the end time of the interval for which to download the data, expressed in UTC in the format "YYYY-MM-DDThh:mm:ss.sssZ" (ISO 8601 standard). If this field is omitted or set to null, it will be automatically set to the current timestamp at the time of the request;

• resampleBy: this parameter allows you to define the frequency at which to calculate the specified KPI. Data in the MAT ecosystem is recorded over time and can be returned either in reference to a time period or as a time series. This field lets you specify how to return the data. The valid values are:

  • unique: this parameter indicates that you want a single numeric value calculated over the entire interval;

  • {n}m: allows the KPI to be calculated with a frequency of {n} minutes over the selected interval;

  • {n}h: allows the KPI to be calculated with a frequency of {n} hours over the selected interval;

  • {n}d: allows the KPI to be calculated with a frequency of {n} days over the selected interval;

  • {n}w: allows the KPI to be calculated with a frequency of {n} weeks over the selected interval;

• limit: this numeric field indicates the maximum number of events to return. The value specified in this key allows you to request the last {n} events. This field can be used in various ways:

  • "limit" without "from" and "to": the last {n} events will be retrieved;

  • "limit" with "from" and without "to": the behavior is the same as the previous case. The last {n} events available will be returned;

  • "limit" with "from" and "to": in this case, the last {n} events will be returned, with the end time of the interval taken from the "to" field. The events will be the last written before the timestamp specified in the "to" field;

  • "limit" with "to" and without "from": this option is not allowed and will result in an error;

• filterBy: through this field, you can specify a filter to be applied to the cycles. The value must be a dictionary where the keys represent the fields to filter on, and the values represent what is to be accepted for each field. Cycles that do not meet the filter criteria will be discarded;

• calendar : boolean value indicating whether the calendar should be considered in data analysis. By default, this value is set to false.

The response will return the requested cycles along with some additional information, such as their duration, cycle ID, and the associated aggregators.

Example

Request

HTTP
POST https://matdev.40mat.com/apis/cycles/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "from": "2025-04-01T10:00:00.000Z",
    "to": "2025-04-01T10:00:15.000Z",
    "resampleBy": null,
    "filterBy": null,
    "limit": null
}

This request allows downloading all the cycles that occurred within the specified interval.

The response is as follows:

Response

[
    {
        "_time": "2025-04-01T12:00:01.714",
        "aggr0": "prod2",
        "aggr1": "Peach",
        "aggr2": "format-T",
        "count": 1.0,
        "cycleId": "17435015960",
        "cycleIdPost": "17435016010",
        "duration": 5.406894207000732
    },
    {
        "_time": "2025-04-01T12:00:07.321",
        "aggr0": "prod2",
        "aggr1": "Peach",
        "aggr2": "format-T",
        "count": 1.0,
        "cycleId": "17435016010",
        "cycleIdPost": "17435016070",
        "duration": 5.607038974761963
    },
    {
        "_time": "2025-04-01T12:00:12.528",
        "aggr0": "prod2",
        "aggr1": "Peach",
        "aggr2": "format-T",
        "count": 1.0,
        "cycleId": "17435016070",
        "cycleIdPost": "17435016120",
        "duration": 5.206283092498779
    }
]

Example - resampleBy

The resampleBy field allows you to specify the time-based aggregation to apply to the cycles. Note: In this case, when the resampleBy field is set to a value, the individual cycles are not returned. Instead, only aggregated information about the number of cycles that occurred within each selected time interval is provided.

Request

HTTP
POST https://matdev.40mat.com/apis/cycles/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "from": "2025-04-01T10:00:00.000Z",
    "to": "2025-04-05T10:00:15.000Z",
    "resampleBy": "1d",
    "filterBy": null,
    "limit": null
}

The response is as follows, where count indicates the number of cycles that occurred.

Response

[
    {
        "_time": "2025-04-01T00:00:00.000",
        "aggr0": "prod5$$prod3$$prod4$$prod2",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Peach",
        "aggr2": "format-I$$format-Q$$format-S$$format-B",
        "count": 3930.0,
        "duration": 43205.61328125
    },
    {
        "_time": "2025-04-02T00:00:00.000",
        "aggr0": "prod1$$prod5$$prod3$$prod4$$prod2",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-N$$format-O$$format-C$$format-K",
        "count": 8966.0,
        "duration": 85191.46875
    },
    {
        "_time": "2025-04-03T00:00:00.000",
        "aggr0": "prod1$$prod5$$prod3$$prod4$$prod2",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-N$$format-O$$format-C$$format-H",
        "count": 9118.0,
        "duration": 87618.1875
    },
    {
        "_time": "2025-04-04T00:00:00.000",
        "aggr0": "prod1$$prod5$$prod3$$prod4$$prod2",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-N$$format-O$$format-C$$format-H",
        "count": 8699.0,
        "duration": 86248.359375
    },
    {
        "_time": "2025-04-05T00:00:00.000",
        "aggr0": "prod1$$prod5$$prod3$$prod4$$prod2",
        "aggr1": "Mario$$Luigi$$Wario$$Waluigi",
        "aggr2": "format-Q$$format-I$$format-B$$format-N",
        "count": 3738.0,
        "duration": 42353.62109375
    }
]

If the resampleBy field is set to "unique", the response will return the total number of cycles that occurred within the selected interval.

Example - limit

The limit field allows you to specify how many cycles to retrieve within the selected interval.

Request

HTTP
POST https://matdev.40mat.com/apis/cycles/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "from": "2025-04-01T10:00:00.000Z",
    "to": "2025-04-05T10:00:15.000Z",
    "resampleBy": null,
    "filterBy": null,
    "limit": 2
}

In this case, the request is asking for the last two cycles that occurred within the selected interval. The response is as follows:

Response

[
    {
        "_time": "2025-04-05T11:43:09.362",
        "aggr0": "prod5",
        "aggr1": "Waluigi",
        "aggr2": "format-J",
        "count": 1.0,
        "cycleId": "17438461850",
        "cycleIdPost": "0",
        "duration": 3.608262062072754
    },
    {
        "_time": "2025-04-05T11:43:05.754",
        "aggr0": "prod5",
        "aggr1": "Waluigi",
        "aggr2": "format-J",
        "count": 1.0,
        "cycleId": "17438461800",
        "cycleIdPost": "17438461850",
        "duration": 5.407228946685791
    }
]

Code

Python

The following script can be used to invoke a call to the /apis/cycles/<assetId> endpoint with the POST method. Be sure to correctly configure the parameters in the body of the request.

import requests
import json

# Example data for the header
headers = {
    'App-Name': 'matdev-be',
    'Authorization': 'Bearer ey....xy1w'
}

# Example data for the body
body = {
    "from": "2024-03-31T22:00:00.000Z",
    "to": "2024-04-05T21:59:59.999Z",
    "filterBy": None,
    "limit": None
}


# Example data for the query string
query_params = {
    "subAssetId": "M1"
}

# URL of the third-party API
myDomain = 'matdev.40mat.com'
myAssetId = '40-line'
endpoint = f'/apis/cycles/{myAssetId}'
url = f'https://{myDomain}{endpoint}'

# Make the POST request
response = requests.post(url, headers=headers, json=body, params=query_params )

# Check the response status and return the data
if response.status_code == 200:
    print('Success:')
    print(json.dumps(response.json(), indent=4))
else:
    print('Request failed:')
    print(f'Status code: {response.status_code}')
    print(response.text)