curl -X GET "https://api.submagic.co/v1/projects/published?platform=youtube&from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&sortBy=views&direction=desc&limit=25" \
  -H "x-api-key: sk-your-api-key-here"

{
  "data": [
    {
      "id": "pub_8f3b4c2e-1a9d-4e5f-9b7c-2a4d6e8f1c3b",
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "publishedAt": "2026-04-28T12:34:56.000Z",
      "scheduled": false,
      "status": "published",
      "project": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "How I Doubled My Revenue in 30 Days"
      },
      "totals": {
        "views": 1234,
        "engagement": 65,
        "followersGained": 18
      },
      "posts": [
        {
          "platform": "youtube",
          "platformPostId": "dQw4w9WgXcQ",
          "platformPostUrl": "https://youtube.com/watch?v=dQw4w9WgXcQ",
          "publishStatus": "published",
          "syncStatus": "synced",
          "error": null,
          "analytics": {
            "views": 1234,
            "likes": 56,
            "comments": 7,
            "shares": 2,
            "impressions": 5000,
            "reach": 800,
            "clicks": 120,
            "engagementRate": 0.125
          }
        }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6InB1Yl83YjJjM2Q0ZSJ9"
  }
}

GET

projects

published

curl -X GET "https://api.submagic.co/v1/projects/published?platform=youtube&from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&sortBy=views&direction=desc&limit=25" \
  -H "x-api-key: sk-your-api-key-here"

{
  "data": [
    {
      "id": "pub_8f3b4c2e-1a9d-4e5f-9b7c-2a4d6e8f1c3b",
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "publishedAt": "2026-04-28T12:34:56.000Z",
      "scheduled": false,
      "status": "published",
      "project": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "How I Doubled My Revenue in 30 Days"
      },
      "totals": {
        "views": 1234,
        "engagement": 65,
        "followersGained": 18
      },
      "posts": [
        {
          "platform": "youtube",
          "platformPostId": "dQw4w9WgXcQ",
          "platformPostUrl": "https://youtube.com/watch?v=dQw4w9WgXcQ",
          "publishStatus": "published",
          "syncStatus": "synced",
          "error": null,
          "analytics": {
            "views": 1234,
            "likes": 56,
            "comments": 7,
            "shares": 2,
            "impressions": 5000,
            "reach": 800,
            "clicks": 120,
            "engagementRate": 0.125
          }
        }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6InB1Yl83YjJjM2Q0ZSJ9"
  }
}

List Published Projects

Retrieve a paginated list of your published posts across YouTube, TikTok, Instagram, X (Twitter), Facebook, and LinkedIn. Each entry includes per-platform delivery status, post URLs, and analytics where available, plus a totals rollup aggregated across the post’s platforms.

This endpoint requires authentication.

Authentication

x-api-key

string

required

Your Submagic API key starting with sk-

Query Parameters

platform

string

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

profileId

string

Filter to a single profile (UUID). Copy the id from the Copy profile ID action in the publishing dashboard’s profile selector.

from

string

Start of the date range (ISO 8601). Filters by publishedAt. When omitted, results include everything published up to now.

string

End of the date range (ISO 8601). Filters by publishedAt. Defaults to the current time.

sortBy

string

Sort field. Allowed values: publishedAt, views, engagement. Defaults to publishedAt. views and engagement sort by the aggregated totals.

direction

string

Sort direction: asc or desc. Defaults to desc.

limit

number

Number of items to return per page (1-100). Defaults to 25.

cursor

string

Cursor for pagination. Pass the nextCursor value from a previous response to fetch the next page of results.

Response

data

array

Array of publication objects

Hide Publication Object

string

Unique identifier of the publication

projectId

string

The unique identifier of the underlying project

publishedAt

string

ISO 8601 timestamp of when the publication was published or is scheduled to publish

scheduled

boolean

true if the publication was scheduled for a future time

status

string

Overall publication status: published, scheduled, processing, or failed

project

object

Minimal project metadata

Show Project

string

Project UUID

title

string

Project title

totals

object

Metrics aggregated across the publication’s platforms

Show Totals

views

number

Sum of views across all platforms

engagement

number

Sum of likes, comments, and shares across all platforms

followersGained

number

Net followers gained around the publish time, summed across the publication’s accounts. null when no follower snapshots are available to compute the delta.

posts

array

Array of per-platform post objects

Show Post Object

platform

string

Platform identifier: youtube, tiktok, instagram, twitter, facebook, or linkedin

platformPostId

string

The post ID assigned by the upstream platform

platformPostUrl

string

Public URL of the post on the platform

publishStatus

string

Per-platform delivery status: published, scheduled, processing, or failed

syncStatus

string

Analytics sync status: synced, pending, or failed

error

string

Error message if the post failed to publish, otherwise null

analytics

object

Platform analytics (available once syncStatus is synced)

Show Analytics

views

number

Total views

likes

number

Total likes

comments

number

Total comments

number

Total shares

impressions

number

Total impressions

reach

number

Unique accounts reached

clicks

number

Total link clicks

engagementRate

number

Engagement rate as a decimal (e.g. 0.125 = 12.5%)

pagination

object

Cursor-based pagination metadata

Hide Pagination

nextCursor

string

Cursor to pass as the cursor query parameter to fetch the next page. null or omitted when there are no more results.

curl -X GET "https://api.submagic.co/v1/projects/published?platform=youtube&from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&sortBy=views&direction=desc&limit=25" \
  -H "x-api-key: sk-your-api-key-here"

{
  "data": [
    {
      "id": "pub_8f3b4c2e-1a9d-4e5f-9b7c-2a4d6e8f1c3b",
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "publishedAt": "2026-04-28T12:34:56.000Z",
      "scheduled": false,
      "status": "published",
      "project": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "How I Doubled My Revenue in 30 Days"
      },
      "totals": {
        "views": 1234,
        "engagement": 65,
        "followersGained": 18
      },
      "posts": [
        {
          "platform": "youtube",
          "platformPostId": "dQw4w9WgXcQ",
          "platformPostUrl": "https://youtube.com/watch?v=dQw4w9WgXcQ",
          "publishStatus": "published",
          "syncStatus": "synced",
          "error": null,
          "analytics": {
            "views": 1234,
            "likes": 56,
            "comments": 7,
            "shares": 2,
            "impressions": 5000,
            "reach": 800,
            "clicks": 120,
            "engagementRate": 0.125
          }
        }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6InB1Yl83YjJjM2Q0ZSJ9"
  }
}

Error Responses

400 Validation Error

object

{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "platform",
      "message": "Must be one of: youtube, tiktok, instagram, twitter, facebook, linkedin",
      "value": "snapchat"
    }
  ]
}

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

Publish Project Get Publication

​List Published Projects

​Authentication

​Query Parameters

​Response

​Error Responses

List Published Projects

Authentication

Query Parameters

Response

Error Responses