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

{
  "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

​
x-api-key
string
required
Your Submagic API key starting with sk-

​
Query Parameters

​
from
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.
​
to
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.
​
platform
string
Filter by platform. Allowed values: youtube, tiktok, instagram, twitter, facebook, linkedin.
​
metric
string
Which metric the timeseries returns: views, engagement, or followers. Defaults to views. The summary block always includes all three.

​
Response

​
period
object
The requested window and the prior period used for comparison
​
summary
object
Totals for the current period with prior-period comparison. Each metric is an object with current and prior values.
​
metric
string
The metric the timeseries represents (echoes the metric query parameter)
​
timeseries
array
Daily data points spanning the range (UTC days)
curl -X GET "https://api.submagic.co/v1/publishing/stats" \
  -H "x-api-key: sk-your-api-key-here"

{
  "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

​
400 Validation Error
object
{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "from",
      "message": "Invalid datetime",
      "value": "2026-05-01"
    }
  ]
}
​
401 Unauthorized
object
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
​
429 Rate Limited
object
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 30
}
​
500 Server Error
object
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}