Signal Data¶

Falkonry provides two primary methods for extracting signal data, optimized for different use cases:

Raw Data API (raw_data): Retrieves precise, individual data points in Apache Arrow IPC format. Ideal for high-fidelity data analysis.
Aggregated Data API (cells): Returns statistical summaries (min, max, mean, std, count) in JSON format. Ideal for trend analysis and visualization.

Retrieve raw signal data¶

Returns raw data points.

Pagination: A maximum of 1,000 data points are returned per request. Use the next-time field found in the response headers to paginate and retrieve subsequent data chunks.

Method	Path
`GET`	`/api/1.3/data/accounts/{account_id}/connectedsources/{signal_id}/raw_data`

Query Parameters

Parameter	Type	Required	Description
`start`	`long`	Yes	Start time in nanoseconds.
`end`	`long`	No	End time in nanoseconds. Required if `reverse=true`.
`reverse`	`boolean`	No	Set `true` to scan in descending order (Default: `false`).

cURLPython

curl -H "Authorization: Bearer <token>" -H "Accept: application/x-arrow-ipc" \\
"https://app3.falkonry.ai/api/1.3/data/accounts/{ACCOUNT_ID}/connectedsources/{SIGNAL_ID}/raw_data?start=1640168850582000000&end=1640168940981000000"

import requests, io, pyarrow

URL = "https://app3.falkonry.ai/api/1.3/data/accounts/{ACCOUNT_ID}/connectedsources/{SIGNAL_ID}/raw_data"
params = {'start': 1640168850582000000, 'end': 1640168940981000000}
headers = {'Authorization': 'Bearer <token>', 'Accept': 'application/x-arrow-ipc'}

req = requests.get(URL, headers=headers, params=params)
next_time = req.headers['next-time'] # Pass this as 'start' for the next request

stream = io.BytesIO(req.content)
with pyarrow.ipc.open_stream(stream) as reader:
    df = reader.read_pandas()
    print(df)

Retrieve aggregated signal data¶

Provides statistical data grouped by time intervals.

Method	Path
`GET`	`/api/1.3/accounts/{account_id}/connectedsources/{signal_id}/cells`

Query Parameters

Parameter	Required	Description
`start_time_iso`	Yes	Start time (ISO format).
`end_time_iso`	Yes	End time (ISO format).
`level`	Yes	Aggregation level (determines bucket duration).

Aggregation levels¶

Level	Aggregated Duration
14	1 Day
13	1 Hour
12	10 Minutes
11	1 Minute
10	10 Seconds
9	1 Second
8	100 milliseconds
7	10 milliseconds
6	1 millisecond
5	100 microseconds
4	10 microseconds
3	1 microsecond
2	100 nanoseconds
1	10 nanoseconds

cURLPython

curl -H "Authorization: Bearer <token>" \\
"https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/connectedsources/{SIGNAL_ID}/cells?start_time_iso=2022-08-28T13:00:00Z&end_time_iso=2022-08-30T16:00:00Z&level=13"

import io 
import requests 
import pyarrow

URL = 'https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/connectedsources/{SIGNAL_ID}/cells'
TOKEN = '<token>' 
HEADERS = {'Authorization': f'Bearer {TOKEN}'} 
PARAMS = {'start_time_iso': '2022-08-28T13:00:00.000000Z', 'end_time_iso': '2022-08-30T16:00:00.000000Z', 'level': 13 }
req = requests.get(URL, headers=HEADERS, params=PARAMS)
print(req.json())

Example Response

    {
      "startTime": "2022-08-28T13:00:00Z",
      "endTime": "2022-08-30T16:00:00Z",
      "level": 13,
      "cellDuration": 3600000000000,
      "mean": [0.501, 0.494, 0.500],
      "max": [0.995, 0.999, 0.999],
      "min": [0.001, 0.006, 0.007],
      "std": [0.278, 0.294, 0.289],
      "count": [595, 3597, 3008]
    }

Note

The count field indicates the number of data points per aggregation cell.
The firstpoint field (if present) indicates the start time of the specific aggregated cell.
The API may return cells falling outside the requested range to maintain bucket alignment.

Delete Signal Data¶

TSI is designed to receive large numbers of time series signals. The Connection settings control the data transformation. When data with incorrect time settings get into a signal, the data becomes unusable. In such case, the following API can be used to delete a portion of data. This API returns a flow ID and triggers a long running process.

When deleting the signals data from TSI, it's important to be aware of the implications of such actions:

Irreversible action: Deleting signal data is permanent and cannot be undone. This action should be carefully reviewed, planned, and executed only when absolutely necessary.
Long running process: This action triggers a background process that may take significant time to complete, depending on the data volume. During this process, system performance may be temporarily degraded. Track the status from in-app activity panel.

cURLPython

$ curl --location --request POST 'https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/flows' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "name": "signaldatacleanup flow", 
      "flowType": "SIGNALDATACLEANUP", 
      "spec": { "sourceIds": ["yyyyyyyyyyyy"], 
                "startTime": "YYYY-MM-DDTHH:mm:SS.SSSZ",
                "endTime": "YYYY-MM-DDTHH:mm:SS.SSSZ" 
              }}'

import requests 

URL = 'https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/flows'
TOKEN = '<token>' 
HEADERS = {'Authorization': f'Bearer {TOKEN}'} 
PAYLOAD = { "name": "signaldatacleanup flow", 
              "flowType": "SIGNALDATACLEANUP", 
              "spec": { "sourceIds": ["yyyyyyyyyyyy"], 
                        "startTime": "YYYY-MM-DDTHH:mm:SS.SSSSSSZ",
                          "endTime": "YYYY-MM-DDTHH:mm:SS.SSSSSSZ" 
                      } 
          }

response = requests.post(URL, headers=HEADERS, data=PAYLOAD)
print(response.json())

Example response

{
  "id": "zzzzzzzzzzzzzz",
  "type": "entities.flow",
  "tenant": "xxxxxxxxxxxxxxx",
  "flowType": "SIGNALDATACLEANUP",
  "status": "CREATED",
  "name": "signaldatacleanup flow",
  "spec": {
    "sourceIds": ["yyyyyyyyyyyy"],
    "startTime": "YYYY-MM-DDTHH:mm:SS.SSSSSSZ",
    "endTime": "YYYY-MM-DDTHH:mm:SS.SSSSSSZ"
  }
}

Note

The startTime and endTime should be in UTC timezone.