curl -X GET "https://api.submagic.co/v1/publishing/stats/profiles/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "x-api-key: sk-your-api-key-here"

curl -X GET "https://api.submagic.co/v1/publishing/stats/profiles/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&metric=followers" \
  -H "x-api-key: sk-your-api-key-here"

const getProfileStats = async (
  profileId,
  { 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/profiles/${profileId}?${params}`,
    {
      headers: {
        "x-api-key": "sk-your-api-key-here",
      },
    }
  );

  return response.json();
};

const stats = await getProfileStats(
  "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  { from: "2026-05-01T00:00:00Z", to: "2026-05-31T23:59:59Z", metric: "followers" }
);
console.log(`${stats.profile.name}: ${stats.summary.followers.current} followers`);

import requests

def get_profile_stats(profile_id, date_from, date_to,
                      platform=None, metric=None):
    url = f'https://api.submagic.co/v1/publishing/stats/profiles/{profile_id}'
    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_profile_stats(
    '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
    '2026-05-01T00:00:00Z',
    '2026-05-31T23:59:59Z',
    metric='followers',
)
print(f"{stats['profile']['name']}: {stats['summary']['followers']['current']} followers")

{
  "profile": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "My Brand",
    "isPrimary": true
  },
  "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": 60200, "prior": 51000 },
    "engagement": { "current": 4100, "prior": 3500 },
    "followers": { "current": 15230, "prior": 14800 }
  },
  "metric": "followers",
  "timeseries": [
    {
      "date": "2026-05-01",
      "total": 14820,
      "breakdown": [{ "platform": "tiktok", "value": 14820 }]
    },
    {
      "date": "2026-05-31",
      "total": 15230,
      "breakdown": [{ "platform": "tiktok", "value": 15230 }]
    }
  ]
}

GET

publishing

stats

profiles

{profileId}

curl -X GET "https://api.submagic.co/v1/publishing/stats/profiles/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "x-api-key: sk-your-api-key-here"

curl -X GET "https://api.submagic.co/v1/publishing/stats/profiles/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&metric=followers" \
  -H "x-api-key: sk-your-api-key-here"

const getProfileStats = async (
  profileId,
  { 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/profiles/${profileId}?${params}`,
    {
      headers: {
        "x-api-key": "sk-your-api-key-here",
      },
    }
  );

  return response.json();
};

const stats = await getProfileStats(
  "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  { from: "2026-05-01T00:00:00Z", to: "2026-05-31T23:59:59Z", metric: "followers" }
);
console.log(`${stats.profile.name}: ${stats.summary.followers.current} followers`);

import requests

def get_profile_stats(profile_id, date_from, date_to,
                      platform=None, metric=None):
    url = f'https://api.submagic.co/v1/publishing/stats/profiles/{profile_id}'
    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_profile_stats(
    '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
    '2026-05-01T00:00:00Z',
    '2026-05-31T23:59:59Z',
    metric='followers',
)
print(f"{stats['profile']['name']}: {stats['summary']['followers']['current']} followers")

{
  "profile": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "My Brand",
    "isPrimary": true
  },
  "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": 60200, "prior": 51000 },
    "engagement": { "current": 4100, "prior": 3500 },
    "followers": { "current": 15230, "prior": 14800 }
  },
  "metric": "followers",
  "timeseries": [
    {
      "date": "2026-05-01",
      "total": 14820,
      "breakdown": [{ "platform": "tiktok", "value": 14820 }]
    },
    {
      "date": "2026-05-31",
      "total": 15230,
      "breakdown": [{ "platform": "tiktok", "value": 15230 }]
    }
  ]
}

Profile Stats

The same data as Publishing Stats, but scoped to a single profile (brand) — all connected accounts under that profile. Returns the profile metadata plus summary totals (with prior-period comparison) and a daily time-series for the chosen metric.

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

This endpoint requires authentication.

The {profileId} is the id shown by the Copy profile ID action in the publishing dashboard’s profile selector.

Authentication

string

required

Your Submagic API key starting with sk-

Path Parameters

string

required

The unique identifier (UUID) of the profile to scope the analytics to

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

Metadata for the scoped profile

Show Profile

string

Profile UUID

string

Profile display name

boolean

true if this is your primary profile

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 the profile’s 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/profiles/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "x-api-key: sk-your-api-key-here"

curl -X GET "https://api.submagic.co/v1/publishing/stats/profiles/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&metric=followers" \
  -H "x-api-key: sk-your-api-key-here"

const getProfileStats = async (
  profileId,
  { 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/profiles/${profileId}?${params}`,
    {
      headers: {
        "x-api-key": "sk-your-api-key-here",
      },
    }
  );

  return response.json();
};

const stats = await getProfileStats(
  "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  { from: "2026-05-01T00:00:00Z", to: "2026-05-31T23:59:59Z", metric: "followers" }
);
console.log(`${stats.profile.name}: ${stats.summary.followers.current} followers`);

import requests

def get_profile_stats(profile_id, date_from, date_to,
                      platform=None, metric=None):
    url = f'https://api.submagic.co/v1/publishing/stats/profiles/{profile_id}'
    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_profile_stats(
    '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
    '2026-05-01T00:00:00Z',
    '2026-05-31T23:59:59Z',
    metric='followers',
)
print(f"{stats['profile']['name']}: {stats['summary']['followers']['current']} followers")

{
  "profile": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "My Brand",
    "isPrimary": true
  },
  "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": 60200, "prior": 51000 },
    "engagement": { "current": 4100, "prior": 3500 },
    "followers": { "current": 15230, "prior": 14800 }
  },
  "metric": "followers",
  "timeseries": [
    {
      "date": "2026-05-01",
      "total": 14820,
      "breakdown": [{ "platform": "tiktok", "value": 14820 }]
    },
    {
      "date": "2026-05-31",
      "total": 15230,
      "breakdown": [{ "platform": "tiktok", "value": 15230 }]
    }
  ]
}

Error Responses

object

{
  "error": "NOT_FOUND",
  "message": "Profile not found"
}

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

Profile Stats

Profile Stats

Authentication

Path Parameters

Query Parameters

Response

Error Responses

​Profile Stats

​Authentication

​Path Parameters

​Query Parameters

​Response

​Error Responses

Profile Stats

Authentication

Path Parameters

Query Parameters

Response

Error Responses