Two kinds of data API are commonly used. For metrics, event logs, and entity-related data, it's called Insight API, and you can also use raw SQL API.
For subgraph projects, you can use both SQL API and Subgraph API.
Insight API
The easiest way to build a query is through the UI. You can first create an insight chart,
and then
.png)
The result is like:
curl -L -X POST 'https://app.sentio.xyz/api/v1/metrics/sentio/coinbase/query_range' \
-H 'api-key: <API_KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{
"queries": [
{
"query": "mint_sum",
"alias": "Mint (24 hours)",
"id": "a",
"labelSelector": {},
"aggregate": null,
"functions": [
{
"name": "rollup_sum",
"arguments": [
{
"durationValue": {
"value": 1,
"unit": "d"
}
}
]
}
],
"disabled": false
},
{
"query": "burn_sum",
"alias": "Burn (24 hours)",
"id": "b",
"labelSelector": {},
"aggregate": null,
"functions": [
{
"name": "rollup_sum",
"arguments": [
{
"durationValue": {
"value": 1,
"unit": "d"
}
}
]
}
],
"disabled": false
}
],
"formulas": [],
"timeRange": {
"start": "now-30d",
"end": "now",
"step": 3600,
"timezone": "America/Los_Angeles"
},
"samplesLimit": 20
}'
Time Range Configuration Guide
When configuring a time range, you can specify the start
and end
times, as well as the step
interval and timezone
. Below are the details on how to set these parameters:
-
Start and End Time:
- "now": Represents the current time, usually used in the
end
field. - "now-x[dmsy]": Represents the time range starting from the last specified period until now. For example,
now-30d
means the last 30 days from now. The units can be:- "s" for seconds
- "m" for minutes
- "d" for days
- "w" for weeks
- "mo" for months
- "y" for years
- Milliseconds since January 1, 1970, UTC: You can specify a precise time using the number of milliseconds since the Unix epoch (January 1, 1970, UTC). For example,
1716430188709
.
- "now": Represents the current time, usually used in the
-
Step:
- The interval time of data in seconds. This controls how frequently data points should appear in your range. For example, if you set
step
to3600
, data points will appear at one-hour intervals. Please note that the actual step may be adjusted if the interval is short but the date range is long. Typically, the total number of data points should not exceed 1000.
- The interval time of data in seconds. This controls how frequently data points should appear in your range. For example, if you set
-
Timezone:
- Specify the timezone using the tz database name. You can find the appropriate timezone from this list. For example,
America/New_York
orAsia/Tokyo
.
- Specify the timezone using the tz database name. You can find the appropriate timezone from this list. For example,
Example Configuration
Hereโs an example configuration that uses these parameters:
{
"start": "now-30d",
"end": "now",
"step": 3600,
"timezone": "America/New_York"
}
- Start: The range starts from 30 days ago.
- End: The range ends at the current time.
- Step: Data points are provided every hour.
- Timezone: The times are adjusted to the Eastern Time Zone (America/New_York).
This configuration ensures that you get hourly data points for the last 30 days, adjusted to the specified timezone.
SQL API
For SQL API, go to "Data Studio" -> "SQL Editor", write your query and then click "Export as cURL"
.png)
Then it shows things like
curl -L -X POST 'https://app.sentio.xyz/api/v1/analytics/sentio/coinbase/sql/execute' \
-H 'api-key: <API_KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{
"sqlQuery": {
"sql": "SELECT uniq(distinct_id) FROM `Transfer` \n"
}
}'
Cache Control
Each API can directly control cache strategy by adding a cachePolicy
field as follows. The default cache behavior is to have a long cache TTL and short refresh TTL, so the query is cached most of the time but if it's stale, it triggers background refreshing.
{
...
cache_policy: {
cache_ttl_secs: number // ttl for cache
no_cache: bool // don't use cache for this query (don't do refreshing)
cache_refresh_ttl_secs: number // ttl for triggering background refresh
force_refresh: bool // force caching refresh now on this query.
}
}
API will also return information about the caching and other stats as follows:
{
...
compute_stats: {
computed_at: timestamp // when the result is computed
is_cached: bool // is the result come from cache
is_refreshing: bool // is the background refreshing triggering
}
}
Pagination
The SQL API uses cursor-based pagination for handling large datasets. Follow these steps:
- Initial Request: Send a
POST
request to the API endpoint with the Content-Type:application/json
header and yourapi-key
. The request body should be a JSON object containing thesqlQuery
field:
{
"sqlQuery": {
"sql": "YOUR_SQL_QUERY",
"size": OPTIONAL_PAGE_SIZE
}
}
-
Check Response: Parse the JSON response. If it contains a non-empty
cursor
field, there's more data. -
Subsequent Requests: For the next page, send another
POST
request to the same endpoint with the same headers. The request body should only contain thecursor
field, using the value from the previous response:
{
"cursor": "PREVIOUS_CURSOR_VALUE"
}
-
Repeat: Continue making subsequent requests, updating the
cursor
with the value from each response, until thecursor
field in the response is empty or missing. -
Complete: Once the
cursor
is empty, you have retrieved all the data.
Key Points
- Use the
cursor
from the previous response for the next request. - Do not include the
sqlQuery
field in subsequent requests. - Pagination continues until an empty
cursor
is received.