Metric Versions

• Overview
• Finding Versions
• Why Metrics Have Versions
• How Versions Work
• Querying a Specific Version
• Using Versions in sanpy
• Discovering Available Versions
• Version-Aware Fields
• 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 version 2.0 that uses the same calculation methodology as the previous version but is computed on a larger and more up-to-date set of social media sources.

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
      }
7
    }
8
  }
9
}

To get versions for all metrics, execute:

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

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
    }
8
  }
9
}

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. The most common values are simple numeric strings like "1.0" and "2.0". Experimental versions use descriptive names such as "Experimental (Weighted Age)".

Key points:

• Every metric has at least version "1.0".
• The version parameter scopes the entire getMetric context — all subfields (timeseries data, available slugs, available since, etc.) return data for that version.
• 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".

1
{
2
  getMetric(metric: "social_volume_total", version: "1.0") {
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 version: "1.0":

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 the 1.0 version is the default
11
  v1: getMetric(metric: "social_volume_total", version: "1.0") {
12
    timeseriesDataJson(
13
      slug: "bitcoin"
14
      from: "utc_now-7d"
15
      to: "utc_now"
16
      interval: "1d"
17
    )
18
  }
19
  v2: getMetric(metric: "social_volume_total", version: "2.0") {
20
    timeseriesDataJson(
21
      slug: "bitcoin"
22
      from: "utc_now-7d"
23
      to: "utc_now"
24
      interval: "1d"
25
    )
26
  }
27
}

Both 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']

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="2.0"
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="2.0"
19
)

When version is omitted, "1.0" is used by default — 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
      }
7
    }
8
  }
9
}

1
{
2
  "data": {
3
    "getMetric": {
4
      "metadata": {
5
        "availableVersions": [
6
          {
7
            "version": "1.0"
8
          },
9
          {
10
            "version": "2.0"
11
          }
12
        ]
13
      }
14
    }
15
  }
16
}```
17

18
Most metrics only have version `"1.0"`. Metrics with multiple versions will
19
list all of them.
20

21
### For all metrics
22

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

26
```graphql explorer
27
{
28
  getAccessRestrictions(filter: METRIC) {
29
    name
30
    availableVersions {
31
      version
32
    }
33
  }
34
}

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
    }
8
  }
9
}

1
{
2
  "data": {
3
    "getAccessRestrictions": [
4
      {
5
        "name": "social_volume_total",
6
        "isAccessible": true,
7
        "availableVersions": [
8
          {
9
            "version": "1.0"
10
          },
11
          {
12
            "version": "2.0"
13
          }
14
        ]
15
      }
16
    ]
17
  }
18
}

The version parameter on getMetric affects the following fields:

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

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

The response contains both v1 and v2 objects so you can compare default behavior vs explicit version pinning. After discovering additional versions from availableVersions, replace version: "1.0" with the desired version string and rerun the query. You can apply the same pattern to compare availability:

1
{
2
  v1: getMetric(metric: "social_volume_total", version: "1.0") {
3
    availableSince(slug: "bitcoin")
4
  }
5
  v2: getMetric(metric: "social_volume_total", version: "2.0") {
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 = "1.0" — if you do not provide a version parameter, the API defaults to "1.0". 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") rather than relying on the default. This protects your integration even if the default changes in the future.