Skip to main content
GET
/
v1
/
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"

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

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

​
Path Parameters

​
profileId
string
required
The unique identifier (UUID) of the profile to scope the analytics to

​
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

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

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

​
404 Not Found
object
{
  "error": "NOT_FOUND",
  "message": "Profile not found"
}
​
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"
}