Total Post Reach over Time

Retrieve the total potential follower reach per minute for a token over a specified time range. This represents the cumulative follower count of all accounts that posted during each minute.

Note: Social data collection begins only after a token has migrated from a launchpad or has locked liquidity.

Endpoint

GET https://enterprise.guardis.io/v1/socials/reach-over-time

Authentication

Include your API key in the X-API-Key header.

X-API-Key: your_api_key_here

---

Query Parameters

Parameter	Type	Required	Description
token_address	string	Yes	The mint address of the token
from_date	string	Yes	Start of the time range (ISO 8601 format)
to_date	string	No	End of the time range (ISO 8601 format). Defaults to current time

---

Example Request

curl -X GET "https://enterprise.guardis.io/v1/socials/reach-over-time?token_address=5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump&from_date=2025-12-07T00:00:00Z&to_date=2025-12-07T12:00:00Z" \
  -H "X-API-Key: your_api_key_here"

---

Response Format

{
  "token_address": "5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump",
  "from_date": "2025-12-07T00:00:00Z",
  "to_date": "2025-12-07T12:00:00Z",
  "interval": "1m",
  "data_points": [
    {
      "timestamp": "2025-12-07T00:00:00Z",
      "reach": 14829
    },
    {
      "timestamp": "2025-12-07T00:01:00Z",
      "reach": 847291
    },
    {
      "timestamp": "2025-12-07T00:02:00Z",
      "reach": 2847
    },
    {
      "timestamp": "2025-12-07T00:03:00Z",
      "reach": 52847
    },
    {
      "timestamp": "2025-12-07T00:04:00Z",
      "reach": 1284729
    }
  ]
}

---

Field Reference

Response Wrapper

Field	Type	Description
token_address	string	The mint address of the token
from_date	string	Start of the requested time range
to_date	string	End of the requested time range
interval	string	Data aggregation interval (always 1m for per-minute)
data_points	array	Array of time-series data points

Data Point

Field	Type	Description
timestamp	string	ISO 8601 timestamp for this data point
reach	integer	Total follower count of accounts that posted during this minute

---

Example Usage

JavaScript:

const params = new URLSearchParams({
  token_address: "5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump",
  from_date: "2025-12-07T00:00:00Z",
  to_date: "2025-12-07T12:00:00Z"
});

const response = await fetch(
  `https://enterprise.guardis.io/v1/socials/reach-over-time?${params}`,
  {
    headers: {
      "X-API-Key": "your_api_key_here"
    }
  }
);

const data = await response.json();

console.log(`Reach Over Time (${data.data_points.length} data points)`);

// Find peak reach
const peak = data.data_points.reduce((max, dp) => dp.reach > max.reach ? dp : max);
console.log(`Peak Reach: ${peak.reach.toLocaleString()} followers at ${peak.timestamp}`);

// Calculate total reach
const total = data.data_points.reduce((sum, dp) => sum + dp.reach, 0);
console.log(`Total Reach: ${total.toLocaleString()} followers`);

// Calculate average reach per minute
const avg = total / data.data_points.length;
console.log(`Average Reach/Min: ${avg.toLocaleString()} followers`);

Python:

import requests

response = requests.get(
    "https://enterprise.guardis.io/v1/socials/reach-over-time",
    params={
        "token_address": "5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump",
        "from_date": "2025-12-07T00:00:00Z",
        "to_date": "2025-12-07T12:00:00Z"
    },
    headers={"X-API-Key": "your_api_key_here"}
)

data = response.json()

print(f"Reach Over Time ({len(data['data_points'])} data points)")

# Find peak reach
peak = max(data["data_points"], key=lambda dp: dp["reach"])
print(f"Peak Reach: {peak['reach']:,} followers at {peak['timestamp']}")

# Calculate total reach
total = sum(dp["reach"] for dp in data["data_points"])
print(f"Total Reach: {total:,} followers")

# Calculate average reach per minute
avg = total / len(data["data_points"])
print(f"Average Reach/Min: {avg:,.0f} followers")

---

Error Responses

Status Code	Description
400	Missing required parameters
401	Missing or invalid API key
404	Token not found or social tracking not yet active
422	Invalid date format or date range
500	Internal server error

{
  "code": 400,
  "message": "Missing required parameter: from_date"
}