curl -X GET "https://api.submagic.co/v1/publishing/stats" \
  -H "x-api-key: sk-your-api-key-here"

curl -X GET "https://api.submagic.co/v1/publishing/stats?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&metric=views" \
  -H "x-api-key: sk-your-api-key-here"

const getPublishingStats = async ({ from, to, platform, metric } = {}) => {
  const params = new URLSearchParams();
  if (from) params.set("from", from);
  if (to) params.set("to", to);
  if (platform) params.set("platform", platform);
  if (metric) params.set("metric", metric);

  const response = await fetch(
    `https://api.submagic.co/v1/publishing/stats?${params}`,
    {
      headers: {
        "x-api-key": "sk-your-api-key-here",
      },
    }
  );

  return response.json();
};

const stats = await getPublishingStats({
  from: "2026-05-01T00:00:00Z",
  to: "2026-05-31T23:59:59Z",
  metric: "views",
});
console.log(`Views: ${stats.summary.views.current} (was ${stats.summary.views.prior})`);

import requests

def get_publishing_stats(date_from, date_to, platform=None, metric=None):
    url = 'https://api.submagic.co/v1/publishing/stats'
    headers = {
        'x-api-key': 'sk-your-api-key-here'
    }
    params = {'from': date_from, 'to': date_to}
    if platform:
        params['platform'] = platform
    if metric:
        params['metric'] = metric

    response = requests.get(url, headers=headers, params=params)
    return response.json()

stats = get_publishing_stats(
    '2026-05-01T00:00:00Z',
    '2026-05-31T23:59:59Z',
    metric='views',
)
summary = stats['summary']['views']
print(f"Views: {summary['current']} (was {summary['prior']})")

{
  "period": {
    "from": "2026-05-01T00:00:00.000Z",
    "to": "2026-05-31T23:59:59.000Z",
    "priorFrom": "2026-03-31T00:00:01.000Z",
    "priorTo": "2026-05-01T00:00:00.000Z"
  },
  "summary": {
    "views": { "current": 120400, "prior": 98300 },
    "engagement": { "current": 8420, "prior": 7100 },
    "followers": { "current": 15230, "prior": 14800 }
  },
  "metric": "views",
  "timeseries": [
    {
      "date": "2026-05-01",
      "total": 4200,
      "breakdown": [
        { "platform": "tiktok", "value": 3000 },
        { "platform": "youtube", "value": 1200 }
      ]
    },
    {
      "date": "2026-05-02",
      "total": 5100,
      "breakdown": [{ "platform": "tiktok", "value": 5100 }]
    }
  ]
}

GET

publishing

stats

curl -X GET "https://api.submagic.co/v1/publishing/stats" \
  -H "x-api-key: sk-your-api-key-here"

curl -X GET "https://api.submagic.co/v1/publishing/stats?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&metric=views" \
  -H "x-api-key: sk-your-api-key-here"

const getPublishingStats = async ({ from, to, platform, metric } = {}) => {
  const params = new URLSearchParams();
  if (from) params.set("from", from);
  if (to) params.set("to", to);
  if (platform) params.set("platform", platform);
  if (metric) params.set("metric", metric);

  const response = await fetch(
    `https://api.submagic.co/v1/publishing/stats?${params}`,
    {
      headers: {
        "x-api-key": "sk-your-api-key-here",
      },
    }
  );

  return response.json();
};

const stats = await getPublishingStats({
  from: "2026-05-01T00:00:00Z",
  to: "2026-05-31T23:59:59Z",
  metric: "views",
});
console.log(`Views: ${stats.summary.views.current} (was ${stats.summary.views.prior})`);

import requests

def get_publishing_stats(date_from, date_to, platform=None, metric=None):
    url = 'https://api.submagic.co/v1/publishing/stats'
    headers = {
        'x-api-key': 'sk-your-api-key-here'
    }
    params = {'from': date_from, 'to': date_to}
    if platform:
        params['platform'] = platform
    if metric:
        params['metric'] = metric

    response = requests.get(url, headers=headers, params=params)
    return response.json()

stats = get_publishing_stats(
    '2026-05-01T00:00:00Z',
    '2026-05-31T23:59:59Z',
    metric='views',
)
summary = stats['summary']['views']
print(f"Views: {summary['current']} (was {summary['prior']})")

{
  "period": {
    "from": "2026-05-01T00:00:00.000Z",
    "to": "2026-05-31T23:59:59.000Z",
    "priorFrom": "2026-03-31T00:00:01.000Z",
    "priorTo": "2026-05-01T00:00:00.000Z"
  },
  "summary": {
    "views": { "current": 120400, "prior": 98300 },
    "engagement": { "current": 8420, "prior": 7100 },
    "followers": { "current": 15230, "prior": 14800 }
  },
  "metric": "views",
  "timeseries": [
    {
      "date": "2026-05-01",
      "total": 4200,
      "breakdown": [
        { "platform": "tiktok", "value": 3000 },
        { "platform": "youtube", "value": 1200 }
      ]
    },
    {
      "date": "2026-05-02",
      "total": 5100,
      "breakdown": [{ "platform": "tiktok", "value": 5100 }]
    }
  ]
}

Publishing Stats

Aggregate publishing analytics across all of your connected accounts for a date range. Returns summary totals (views, engagement, followers) with a prior-period comparison, plus a daily time-series with per-platform breakdown for the chosen metric. This mirrors the summary cards and chart on the publishing analytics dashboard.

Both from and to are optional — omit them to get the last 7 days (the dashboard’s default period).

This endpoint requires authentication.

Authentication

string

required

Your Submagic API key starting with sk-

Query Parameters

string

Start of the date range (ISO 8601), e.g. 2026-05-01T00:00:00Z. When both from and to are omitted, the range defaults to the last 7 days.

string

End of the date range (ISO 8601), e.g. 2026-05-31T23:59:59Z. Defaults to the current time. The prior period used for comparison is the equally sized window immediately before from.

string

Filter by platform. Allowed values: youtube, tiktok, instagram, twitter, facebook, linkedin.

string

Which metric the timeseries returns: views, engagement, or followers. Defaults to views. The summary block always includes all three.

Response

object

The requested window and the prior period used for comparison

Show Period

string

Start of the requested range (ISO 8601)

string

End of the requested range (ISO 8601)

string

Start of the prior comparison period

string

End of the prior comparison period

object

Totals for the current period with prior-period comparison. Each metric is an object with current and prior values.

Show Summary

object

{ current, prior } — total views

object

{ current, prior } — total likes + comments + shares

object

{ current, prior } — total followers across connected accounts

string

The metric the timeseries represents (echoes the metric query parameter)

array

Daily data points spanning the range (UTC days)

Show Data Point

string

Day in YYYY-MM-DD format

number

Total value of the selected metric for that day

array

Per-platform split of the day’s total

Show Breakdown Item

string

Platform identifier

number

Value for that platform on that day

curl -X GET "https://api.submagic.co/v1/publishing/stats" \
  -H "x-api-key: sk-your-api-key-here"

curl -X GET "https://api.submagic.co/v1/publishing/stats?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&metric=views" \
  -H "x-api-key: sk-your-api-key-here"

const getPublishingStats = async ({ from, to, platform, metric } = {}) => {
  const params = new URLSearchParams();
  if (from) params.set("from", from);
  if (to) params.set("to", to);
  if (platform) params.set("platform", platform);
  if (metric) params.set("metric", metric);

  const response = await fetch(
    `https://api.submagic.co/v1/publishing/stats?${params}`,
    {
      headers: {
        "x-api-key": "sk-your-api-key-here",
      },
    }
  );

  return response.json();
};

const stats = await getPublishingStats({
  from: "2026-05-01T00:00:00Z",
  to: "2026-05-31T23:59:59Z",
  metric: "views",
});
console.log(`Views: ${stats.summary.views.current} (was ${stats.summary.views.prior})`);

import requests

def get_publishing_stats(date_from, date_to, platform=None, metric=None):
    url = 'https://api.submagic.co/v1/publishing/stats'
    headers = {
        'x-api-key': 'sk-your-api-key-here'
    }
    params = {'from': date_from, 'to': date_to}
    if platform:
        params['platform'] = platform
    if metric:
        params['metric'] = metric

    response = requests.get(url, headers=headers, params=params)
    return response.json()

stats = get_publishing_stats(
    '2026-05-01T00:00:00Z',
    '2026-05-31T23:59:59Z',
    metric='views',
)
summary = stats['summary']['views']
print(f"Views: {summary['current']} (was {summary['prior']})")

{
  "period": {
    "from": "2026-05-01T00:00:00.000Z",
    "to": "2026-05-31T23:59:59.000Z",
    "priorFrom": "2026-03-31T00:00:01.000Z",
    "priorTo": "2026-05-01T00:00:00.000Z"
  },
  "summary": {
    "views": { "current": 120400, "prior": 98300 },
    "engagement": { "current": 8420, "prior": 7100 },
    "followers": { "current": 15230, "prior": 14800 }
  },
  "metric": "views",
  "timeseries": [
    {
      "date": "2026-05-01",
      "total": 4200,
      "breakdown": [
        { "platform": "tiktok", "value": 3000 },
        { "platform": "youtube", "value": 1200 }
      ]
    },
    {
      "date": "2026-05-02",
      "total": 5100,
      "breakdown": [{ "platform": "tiktok", "value": 5100 }]
    }
  ]
}

Error Responses

object

{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "from",
      "message": "Invalid datetime",
      "value": "2026-05-01"
    }
  ]
}

object

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

object

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 30
}

object

{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}

Get Started

Guides

API Reference

Publishing Stats

Publishing Stats

Authentication

Query Parameters

Response

Error Responses

​Publishing Stats

​Authentication

​Query Parameters

​Response

​Error Responses

Publishing Stats

Authentication

Query Parameters

Response

Error Responses