Skip to main content

Fetching data

info

You will need to get a personal access token to use the search API.

The search API is used to fetch the right kind of data depending on your usage.

Getting started​

Here is a sample request around the search API, where we will fetch BUILDING_GROUPs and BUILDINGs.

You need to pass a query with something like that:

📄 search.sh
#!/bin/sh -ex

# Your organization
STONAL_ORG=DEMO

# Fetch your token from here: https://app.stonal.io/users/app
STONAL_TOKEN=9631e269-e21e-4ce6-92a9-c6f7ed1fa98a

curl \
  https://api.stonal.io/datalake/v1/organizations/$STONAL_ORG/assets/search \
  -v \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $STONAL_TOKEN" \
  -d @query.json -o output.json

The query:

📄 query.json
{
    "search": {
        "type": {
            "equals": [
                "BUILDING",
                "BUILDING_GROUP"
            ]
        }
    },
    "fields": [
        "name",
        "type",
        "uid",
        "externalIds"
    ],
    "paginate": {
        "size": 500,
        "cursor": "0"
    }
}

The output

📄 output.json
{
    "assets": [
        {
            "uid": "f6472f1a-9473-4fbf-9e1c-1c063eebb430",
            "name": "Building Group 1",
            "type": "BUILDING_GROUP",
            "externalIds": {
                "CODE": "BG001"
            }
        },
        {
            "uid": "b81ce341-86f0-4cfe-a806-1d4a0f9a12ed",
            "name": "Building 1",
            "type": "BUILDING",
            "externalIds": {
                "CODE": "B001"
            }
        }
    ],
    "paginate": {
        "size": 10,
        "cursor": "123456"
    }
}

Then to fetch the next batch of 10 assets, you shall issue the same query with the paginate.cursor set to the received value, ie "123456".

Going further​

There are many other ways to query data. And you can mix any of these filters.

Matching on a pattern​

You can search for types matching a regex pattern.

🔎 asset type pattern
"search": {
    "type": {
        "pattern": [
            "BUILDING.*"
        ]
    }
}

Differencial update​

You can search data that has been updated since a particular date.

🔎 differencial update
"search": {
    "updatedAtAfter":"2025-09-12T00:00:00"
}

Detect deleted assets​

🔎 detect deleted assets
"search": {
    "updatedAtAfter":"2025-09-12T00:00:00",
    "deleted": true
}