Metric Versions

• Overview
• Finding Versions
• Why Metrics Have Versions
• How Versions Work
• Querying a Specific Version
• Using Versions in sanpy
• Discovering Available Versions
• Version Access by Plan
• Version-Aware Fields
• Update Lag per Version
• Comparing Versions
• Experimental Versions
• Default Behavior and Backward Compatibility

Some metrics in the Santiment API have multiple versions. Each version represents a different implementation, calculation methodology, or underlying data source used to compute the metric.

You can select the desired version using the version parameter in the getMetric query.

Different versions of the same metric typically exist when improvements are made to the calculation process or when the metric starts using a different dataset. This allows us to introduce enhancements without altering the historical behavior of existing versions.

For example, social metrics have a modern:v1 version that is computed on a dataset of currently active Crypto Twitter users, alongside the long-running original:v1 dataset. See Social Data Versions for the list of social versions and when to use each one.

Adding new social accounts or servers to an existing metric version could change its historical values. Alternatively, if historical recomputation is not performed, the introduction of new sources may create artificial spikes in the data. These spikes do not reflect real changes in social activity but are simply the result of expanding the underlying data coverage.

This page covers version semantics in detail. For a general introduction to getMetric and its fields, see Fetching Metrics.

To get versions for a single metric, execute:

1
{
2
  getMetric(metric: "social_volume_total") {
3
    metadata {
4
      availableVersions {
5
        version
6
        versionName
7
      }
8
    }
9
  }
10
}

To get versions for all metrics, execute:

1
{
2
  getAccessRestrictions(filter: METRIC) {
3
    name
4
    availableVersions {
5
      version
6
      versionName
7
    }
8
  }
9
}

To get versions for a specific product and plan, execute:

1
{
2
  getAccessRestrictions(product: SANAPI, plan: BUSINESS_PRO, filter: METRIC) {
3
    name
4
    isAccessible
5
    availableVersions {
6
      version
7
      versionName
8
    }
9
  }
10
}

Analytical methodologies evolve over time. When Santiment improves how a metric is calculated, the updated logic is published as a new version rather than overwriting the original. This approach provides several benefits:

• Historical stability — data you have already queried or stored does not change retroactively, because the original version continues to return the same results.
• Backward compatibility — existing integrations, dashboards, and alerts keep working without modification.
• Side-by-side comparison — you can compare the old and new calculation to understand how the methodology has changed before migrating.

Each version is identified by a version string. Most metrics use simple numeric strings like "1.0" and "2.0". Social metrics also have named social data versions: "original:v1", "modern:v1", and "modern_pit:v1". Experimental versions use descriptive names such as "Experimental (Weighted Age)".

Each entry in availableVersions has these fields:

For social metrics, the names map to numbers like this:

Key points:

• Every non-social metric has at least version "1.0". Every social metric has at least version "original:v1".
• The version parameter scopes the entire getMetric context — all subfields (timeseries data, available slugs, available since, etc.) return data for that version.
• Numeric versions are sorted in semantic order: "1.0" < "2.0" < "3.0", with experimental versions listed after stable ones.

Pass the version argument to getMetric. When omitted, it defaults to "1.0", or to "original:v1" for social metrics.

1
{
2
  getMetric(metric: "social_volume_total", version: "original:v1") {
3
    timeseriesDataJson(
4
      slug: "bitcoin"
5
      from: "utc_now-30d"
6
      to: "utc_now"
7
      interval: "1d"
8
    )
9
  }
10
}

Omitting the version parameter is equivalent to specifying the default version. For the social metric below, that is version: "original:v1":

1
{
2
  noVersion: getMetric(metric: "social_volume_total") {
3
    timeseriesDataJson(
4
      slug: "bitcoin"
5
      from: "utc_now-7d"
6
      to: "utc_now"
7
      interval: "1d"
8
    )
9
  }
10
  # Will return the same data as noVersion, as original:v1 is the default
11
  original: getMetric(metric: "social_volume_total", version: "original:v1") {
12
    timeseriesDataJson(
13
      slug: "bitcoin"
14
      from: "utc_now-7d"
15
      to: "utc_now"
16
      interval: "1d"
17
    )
18
  }
19
  modern: getMetric(metric: "social_volume_total", version: "modern:v1") {
20
    timeseriesDataJson(
21
      slug: "bitcoin"
22
      from: "utc_now-7d"
23
      to: "utc_now"
24
      interval: "1d"
25
    )
26
  }
27
}

The noVersion and original aliases above return identical results.

The sanpy Python library (0.12.6+) supports versioned metrics. You can check which versions a metric has and pass the desired version to san.get or san.get_many.

Check available versions for a metric:

1
import san
2

3
san.available_metric_versions("social_dominance_total")
4
# ['1.0', '2.0', '2.1']

available_metric_versions returns the numeric version values. To get the version names, query versionName through the API.

Fetch data for a specific version:

1
import san
2

3
san.get(
4
    "social_dominance_total",
5
    slug="bitcoin",
6
    from_date="2026-01-01",
7
    to_date="2026-01-10",
8
    interval="1d",
9
    version="modern:v1"
10
)
11

12
san.get_many(
13
    "social_dominance_total",
14
    slugs=["bitcoin", "ethereum"],
15
    from_date="2026-01-01",
16
    to_date="2026-01-10",
17
    interval="1d",
18
    version="modern:v1"
19
)

When version is omitted, the default version ("1.0", or "original:v1" for social metrics) is used — the same behavior as the GraphQL API.

The santiment-research-quickstart repository contains additional examples and Agent skills that can work with versioned metrics.

Use the availableVersions field inside the metadata query:

1
{
2
  getMetric(metric: "social_volume_total") {
3
    metadata {
4
      availableVersions {
5
        version
6
        versionName
7
      }
8
    }
9
  }
10
}

1
{
2
  "data": {
3
    "getMetric": {
4
      "metadata": {
5
        "availableVersions": [
6
          {
7
            "version": "1.0",
8
            "versionName": "original:v1"
9
          },
10
          {
11
            "version": "2.0",
12
            "versionName": "modern:v1"
13
          },
14
          {
15
            "version": "2.1",
16
            "versionName": "modern_pit:v1"
17
          }
18
        ]
19
      }
20
    }
21
  }
22
}

Most non-social metrics only have version "1.0". Metrics with multiple versions will list all of them.

Use the availableVersions field on the getAccessRestrictions query to fetch versions for every metric at once:

1
{
2
  getAccessRestrictions(filter: METRIC) {
3
    name
4
    availableVersions {
5
      version
6
      versionName
7
    }
8
  }
9
}

For a specific product and plan, execute:

1
{
2
  getAccessRestrictions(product: SANAPI, plan: BUSINESS_PRO, filter: METRIC) {
3
    name
4
    isAccessible
5
    availableVersions {
6
      version
7
      versionName
8
    }
9
  }
10
}

1
{
2
  "data": {
3
    "getAccessRestrictions": [
4
      {
5
        "name": "social_volume_total",
6
        "isAccessible": true,
7
        "availableVersions": [
8
          {
9
            "version": "1.0",
10
            "versionName": "original:v1"
11
          },
12
          {
13
            "version": "2.0",
14
            "versionName": "modern:v1"
15
          },
16
          {
17
            "version": "2.1",
18
            "versionName": "modern_pit:v1"
19
          }
20
        ]
21
      }
22
    ]
23
  }
24
}

Newer social data versions need a higher subscription plan than the default "original:v1":

If you request a version your plan does not include, that getMetric alias returns null and the response has an error like this one:

Metric version modern_pit:v1 requires a paid yearly SanAPI Business Max subscription. Anonymous requests have access to original:v1.

Other aliases in the same request still return data.

The version parameter on getMetric affects the following fields:

Versions of the same metric do not all finalize a bar at the same time. This affects how soon after a bar closes you can treat its value as final:

If you compare "original:v1" and "modern_pit:v1" for the most recent hours, expect the "original:v1" values to keep changing while the "modern_pit:v1" values stay fixed.

You can compare versioned query outputs side-by-side in a single request by using GraphQL aliases.

1
{
2
  original: getMetric(metric: "social_volume_total", version: "original:v1") {
3
    timeseriesDataJson(
4
      slug: "bitcoin"
5
      from: "utc_now-7d"
6
      to: "utc_now"
7
      interval: "1d"
8
    )
9
  }
10
  modern: getMetric(metric: "social_volume_total", version: "modern:v1") {
11
    timeseriesDataJson(
12
      slug: "bitcoin"
13
      from: "utc_now-7d"
14
      to: "utc_now"
15
      interval: "1d"
16
    )
17
  }
18
}

The response contains both original and modern objects so you can compare the two datasets. After discovering additional versions from availableVersions, replace version: "modern:v1" with the desired version string and rerun the query. You can apply the same pattern to compare availability:

1
{
2
  original: getMetric(metric: "social_volume_total", version: "original:v1") {
3
    availableSince(slug: "bitcoin")
4
  }
5
  modern: getMetric(metric: "social_volume_total", version: "modern:v1") {
6
    availableSince(slug: "bitcoin")
7
  }
8
}

Some metrics have experimental versions with descriptive names like "Experimental (Weighted Age)". These differ from stable versions in several ways:

• Access requirements — experimental versions are only accessible to users with alpha-level metric access. Querying an experimental version without the required access level returns an error.
• Naming convention — experimental version strings start with "Experimental" followed by a short description in parentheses, making them easy to identify in the availableVersions list.
• Stability — experimental versions may change without notice. They are intended for testing and evaluation, not for production use.

• No version = default version — if you do not provide a version parameter, the API defaults to "1.0", or to "original:v1" for social metrics. This means all existing queries that were written before versions were introduced continue to work exactly as before.
• Existing integrations are unaffected — introducing a new version of a metric does not change the behavior of the default version. Your dashboards, alerts, and scripts will keep returning the same data.
• Pin versions in production — if you rely on a specific version, pass it explicitly (e.g. version: "1.0" or version: "modern:v1") rather than relying on the default. This protects your integration even if the default changes in the future.