Fetching Metrics

• Overview
• Available Metrics
• Metrics Restrictions Per Plan
• Metrics Documentation
• Available Assets
• Available Metrics Per Project
• Available Projects Per Metric
• Minimal Interval
• Aggregation
• Queryable Fields
  • timeseriesData
  • aggregatedTimeseriesData
  • histogramData
  • metadata
  • availableSince
  • lastDatetimeComputedAt
• Examples

Overview

The getMetric GraphQL query provides a unified method for accessing a variety of metrics across all supported assets. This query enables you to retrieve metadata, datetime availability, and various metric representations, including timeseries data, histogram data, and aggregated timeseries data.

Here is an example of a GraphQL getMetric query:

1
2
3
4
5
6
7
8
9
10
11
12
{
  getMetric(metric: "active_addresses_24h") {
    timeseriesData(
      slug: "bitcoin"
      from: "2023-05-01T08:00:00Z"
      to: "2023-05-02T08:00:00Z"
      interval: "30m") {
        datetime
        value
    }
  }
}

This query retrieves the timeseries data for the metric "active_addresses_24h" for Bitcoin, from 8:00 on May 1, 2023, to 8:00 on May 2, 2023, with a 30-minute interval between data points.

Available Metrics

You can fetch the list of all available metrics using the following query:

1
2
3
{
  getAvailableMetrics
}

To fetch the list of available metrics for a specific plan and product, provide the plan and product arguments in the query:

1
2
3
{
  getAvailableMetrics(product: SANAPI plan: PRO)
}

Metrics restrictions per plan

Access to certain metrics may be limited in various ways based on your subscription plan:

• Some metrics may not be accessible to users on lower-tier subscription plans.
• Lower-tier subscription plans may have limited access to certain metrics, excluding access to historical and real-time data.

You can obtain detailed information about the restrictions on all metrics for a specific subscription plan using this query.

Here is an example of a GraphQL query:

1
2
3
4
5
6
7
8
9
10
11
{
  getAccessRestrictions(product: SANAPI plan: PRO){
    name
    type
    minInterval
    isAccessible
    isRestricted
    restrictedFrom
    restrictedTo
  }
}

Metrics Documentation

You can find the documentation for most of the metrics on this page.

Available Assets

Each metric is retrieved for a specific asset, which is identified by its slug.

Instructions on how to fetch all available assets can be found in our Glossary. You can obtain a list of all slugs using this query:

1
2
3
4
5
{
  allProjects{
    slug
  }
}

Available metrics per project

The range of available metrics varies for each asset. The query below demonstrates three distinct lists:

• All accessible metrics
• A subset of all accessible metrics that are timeseries metrics
• A subset of all accessible metrics that are histogram metrics

You can retrieve these lists of metrics using this query:

1
2
3
4
5
6
7
{
  projectBySlug(slug: "ethereum") {
    availableMetrics
    availableTimeseriesMetrics
    availableHistogramMetrics
  }
}

Available projects per metric

The getMetric API supports a comprehensive list of assets, each identified by a unique slug. To fetch the list of available slugs for a specific metric, use the following query:

1
2
3
4
5
6
7
{
  getMetric(metric: "mvrv_usd"){
    metadata{
      availableSlugs
    }
  }
}

Run in explorer

Minimal Interval

Metrics are stored as pairs of datetime and value. The term minInterval refers to the time interval between two consecutive data points. It signifies the smallest interval that can be utilized when querying the metric.

The most frequently used minIntervals include:

• 1 day (1d): Metrics with this interval are typically referred to as "daily" metrics.
• 5 minutes (5m): Metrics with this interval are often called "intraday" metrics.

When querying data, the interval argument is used to determine the resolution of the data. This interval can be significantly larger than the minInterval. In such instances, all the values within that larger interval must be aggregated into a single value. The aggregation parameter controls how this data is aggregated.

Aggregation

Fields that return timeseries data accept an aggregation parameter. When an interval larger than minInterval is provided for a specific metric, multiple data point values will be consolidated into a single data point.

Note: Each metric has a manually selected default aggregation that is used if the aggregation parameter is not specified. The default aggregation is chosen to be the most logical one.

The types of aggregations are:

• SUM - The total of all values.
• AVG - The average of the values.
• MEDIAN - The median of all values.
• FIRST - The earliest value (with the smallest datetime).
• LAST - The most recent value (with the latest datetime).
• MAX - The largest value.
• MIN - The smallest value.
• ANY - Any value within the interval. This is typically used when all values are expected to be the same, and you just want to select one of them. No metrics use this as their default aggregation. This type of aggregation is more commonly used when users write their own SQL queries using the Santiment Queries product.

Note: The aggregation is of the GraphQL enum type and should be provided in uppercase without quotes, like this: aggregation: MAX.

The following query retrieves the default aggregation and all available aggregations for each metric:

1
2
3
4
5
6
7
8
{
  getMetric(metric: "daily_active_addresses") {
    metadata {
      defaultAggregation
      availableAggregations
    }
  }
}

Run in explorer

Queryable fields

In the getMetric function, you can query the following fields:

• timeseriesData
• timeseriesDataPerSlug
• aggregatedTimeseriesData
• histogramData
• metadata
• availableSince
• lastDatetimeComputedAt

timeseriesData

Timeseries data is a sequence of data points collected at consistent intervals over time. Each data point provided by the API includes a datetime and a value field.

To retrieve the values for a specific metric, slug, and time range, you can use the timeseriesData subquery of the getMetric API.

Parameters:

• aggregation: This parameter is optional. If not provided, each metric has a default aggregation that is most suitable. You can view the default aggregation function using the metadata query.

• includeIncompleteData: In some cases, if the day is not yet complete, the current value can be misleading. For instance, fetching daily active addresses at 12pm would include only half a day's data, potentially making the data for that day appear too low.

• transform: Apply a transformation to the timeseries data result. Available transformations include:

  • {type: "none"}: Do not apply any transformation
  • {type: "moving_average", moving_average_base: base}: Apply a simple moving average. Each data point value is calculated as the average of the last base intervals. To compute this, it fetches enough data before from so it can be computed.
  • {type: "changes"}: For each data point, change the value to the difference between the value and the previous value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  getMetric(metric: "dev_activity") {
    timeseriesData(
      slug: "santiment"
      from: "2019-01-01T00:00:00Z"
      to: "2019-09-01T00:00:00Z"
      includeIncompleteData: true
      interval: "7d"
      aggregation: SUM
      transform: { type: "moving_average", moving_average_base: 3 }
    ) {
      datetime
      value
    }
  }
}

Run in explorer

aggregatedTimeseriesData

Aggregated timeseries data is useful when you require a single value instead of multiple values separated by an even interval. This can be utilized to fetch the All-Time High (ATH) price or the highest number of daily active addresses, among other examples.

Parameters:

• aggregation: This parameter is optional. If not provided, each metric has a default aggregation function that is most suitable. The default aggregation function can be viewed using the metadata query.

The following query fetches the all-time highest price for Santiment:

1
2
3
4
5
6
7
8
9
10
{
  getMetric(metric: "price_usd") {
    highest_price: aggregatedTimeseriesData(
      slug: "santiment"
      from: "2017-07-01T00:00:00Z"
      to: "2020-04-01T00:00:00Z"
      aggregation: MAX
    )
  }
}

Run in Explorer

histogramData

A histogram is a graphical representation that organizes a group of data points into a specified range. For instance, if we consider the period from January 2018 to January 2019, we can fetch the amount of Ether that was bought in every 100-dollar price range: $0-$100, $100-$200, ..., $1300-$1400.

To fetch the values for a given histogram metric, slug, and time interval, you can use the histogramData subquery of the getMetric API.

Parameters:

Different histogram metrics may have different response types or formats.

Run in explorer

• availableMetrics - The list of all metrics.
• availableTimeseriesMetrics - The subset of the available metrics that can be fetched via the timeseriesData field.
• availableHistogramMetrics - The subset of the available metrics that can be fetched via the histogramData field.

Run in explorer

metadata

Each metric is accompanied by metadata that describes the following:

• The minimum interval for which it can be fetched. Different metrics are available at varying granularities.
• The default aggregation that will be used when retrieving the metric at a higher resolution.
• The supported aggregations for the metric.
• The existing selectors for the metric.
• The projects for which the metric is available.
• The type of the metric, which can be either a timeseries or a histogram.

1
2
3
4
5
6
7
8
9
10
11
12
{
  getMetric(metric: "daily_active_addresses") {
    metadata {
      availableAggregations
      availableSelectors
      availableSlugs
      dataType
      defaultAggregation
      minInterval
    }
  }
}

Run in explorer

availableSince

You can fetch the date from which a specific metric is available for an asset using the following query:

1
2
3
4
5
{
  getMetric(metric: "transaction_volume") {
    availableSince(slug: "bitcoin")
  }
}

Typically, a metric is available for a given asset from the moment the contract or blockchain is created. However, there are exceptions. For instance, if the calculation of a metric requires pricing data that is not available, the metric will only be available from the date the pricing data becomes available.

For example, Bitcoin has been operational since early 2009, but there were no exchanges or markets for over a year. Therefore, the pricing data only starts from July 2010. As a result, the MVRV metric, which requires market capitalization, is also only available since July 2010.

Run in explorer

lastDatetimeComputedAt

Note: This field may be complex to understand. However, in most scenarios, it's not necessary to comprehend its value.

The lastDatetimeComputedAt field is utilized to retrieve the datetime for which the last data point for the metric/slug pair was computed:

1
2
3
4
5
{
  getMetric(metric: "daily_active_addresses") {
    lastDatetimeComputedAt(slug: "santiment")
  }
}

Understanding the last datetime computed can be crucial in certain situations. Daily metrics (metrics that have one value per day) are recalculated multiple times throughout the day. Each recalculation includes more data than the previous one.

Note: In many instances, such incomplete days can result in misleading data. For example, the Daily Active Address might appear significantly lower than usual. This discrepancy could be due to the fact that only half a day's data is included. By default, the includeIncompleteData flag in timeseriesData is set to false. Therefore, the current day's data will only be visible once the day has ended.

Run in explorer

Examples

Timeseries Data Example

1
2
3
4
5
6
7
8
9
10
11
12
{
  getMetric(metric: "active_addresses_24h") {
    timeseriesData(
      slug: "bitcoin"
      from: "2023-05-01T08:00:00Z"
      to: "2023-05-02T08:00:00Z"
      interval: "30m") {
        datetime
        value
    }
  }
}

Run in Explorer

Timeseries Data Example

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  getMetric(metric: "twitter_followers") {
    timeseriesData(
      slug: "maker"
      from: "2023-01-01T00:00:00Z"
      to: "2023-02-01T00:00:00Z"
      interval: "7d"
      transform: {type: "consecutive_differences"}) {
        datetime
        value
    }
  }
}

Run in Explorer

Aggregated Timeseries Data Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  getMetric(metric: "daily_active_addresses") {
    highest_daa: aggregatedTimeseriesData(
        slug: "ethereum"
        from: "2022-01-01T00:00:00Z"
        to: "2023-01-01T00:00:00Z"
      	aggregation: MAX
      )
    lowest_daa: aggregatedTimeseriesData(
        slug: "ethereum"
        from: "2022-01-01T00:00:00Z"
        to: "2023-01-01T00:00:00Z"
      	aggregation: MIN
      )
  }
}

Run in Explorer

Histogram Metric Example I

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  getMetric(metric: "age_distribution") {
    histogramData(
      slug: "santiment"
      from: "2020-02-10T07:00:00Z"
      to: "2020-03-30T07:00:00Z"
      interval: "1d"
    ) {
      values {
        ... on DatetimeRangeFloatValueList {
          data {
            range
            value
          }
        }
      }
    }
  }
}

Run in Explorer

The response result is a list that contains a 2-element range of datetimes and a float value.

Histogram Metric Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  getMetric(metric: "price_histogram") {
    histogramData(
      slug: "santiment"
      from: "2020-02-10T07:00:00Z"
      to: "2020-03-30T07:00:00Z"
      interval: "1d"
    ) {
      values {
        ... on FloatRangeFloatValueList {
          data {
            range
            value
          }
        }
      }
    }
  }
}

Run in Explorer

The response result is a list that contains a 2-element range of float (prices) and a float value.