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 for all supported assets. This query enables you to retrieve metadata, datetime availability, assets 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.

Run the query in the GraphiQL Explorer

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: BUSINESS_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, or no access at all.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  getAccessRestrictions(product: SANAPI plan: BUSINESS_PRO filter: METRIC) {
    name
    minInterval
    isAccessible
    isRestricted
    isDeprecated
    restrictedFrom
    restrictedTo
    docs {
      link
    }
  }
}

The following fields are selected:

• name - the name of the metric
• minInterval - what is the minimal interval between two data points (5 minutes or 1 day in most cases)
• isDeprecated - is the deprecated. If true, you must stop using this metric as it will be removed in the future.
• isAccessible - is the metric accessible with the selected subscription plan.
• restrictedFrom - what is the earliest date for which this subscription plan can fetch data. If null, then no restrictions apply.
• restrictedTo - what is the latest date for which this subscription plan can fetch data. If null, then no restrictions apply.
• docs - link to the documentation of the metric.

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. You can obtain a list of all slugs using this query:

1
2
3
4
5
6
7
{
  allProjects{
    slug
    name
    ticker
  }
}

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

To fetch the list of available slugs for a specific metric, use the query:

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

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 sum 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

aggregatedTimeseriesData on the project type

Queries like allProject or projectBySlug also have aggregatedTimeseriesData field that works the same way. The only difference is that when using getMetric the metric is already pinned and the slug needs to be provided, while for allProjects and projectBySlug it is vice versa. Using aliases, the aggregatedTimeseriesData can be selected multiple times.

1
2
3
4
5
6
7
{
  allProjects(page: 1 pageSize: 20){
    slug
    devActivity: aggregatedTimeseriesData(metric: "dev_activity_1d" from: "utc_now-30d" to: "utc_now" aggregation: SUM)
    priceUsd: aggregatedTimeseriesData(metric: "price_usd" from: "utc_now-1d" to: "utc_now" aggregation: LAST)
  }
}

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 the general case, this field is not used.

The lastDatetimeComputedAt shows the when the latest data point was computed.

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

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 is a list that contains a 2-element range of float (prices) and a float value.