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"
const listPublishedProjects = async ({
platform,
profileId,
from,
to,
sortBy,
direction,
limit,
cursor,
} = {}) => {
const params = new URLSearchParams();
if (platform) params.set("platform", platform);
if (profileId) params.set("profileId", profileId);
if (from) params.set("from", from);
if (to) params.set("to", to);
if (sortBy) params.set("sortBy", sortBy);
if (direction) params.set("direction", direction);
if (limit) params.set("limit", String(limit));
if (cursor) params.set("cursor", cursor);
const response = await fetch(
`https://api.submagic.co/v1/projects/published?${params}`,
{
headers: {
"x-api-key": "sk-your-api-key-here",
},
}
);
const data = await response.json();
console.log(`Fetched ${data.data.length} publications`);
return data;
};
// Fetch first page of YouTube publications
const page = await listPublishedProjects({ platform: "youtube", limit: 25 });
// Fetch next page
if (page.pagination.nextCursor) {
const nextPage = await listPublishedProjects({
platform: "youtube",
limit: 25,
cursor: page.pagination.nextCursor,
});
}
import requests
def list_published_projects(platform=None, profile_id=None, date_from=None,
date_to=None, sort_by=None, direction=None,
limit=None, cursor=None):
url = 'https://api.submagic.co/v1/projects/published'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
params = {}
if platform:
params['platform'] = platform
if profile_id:
params['profileId'] = profile_id
if date_from:
params['from'] = date_from
if date_to:
params['to'] = date_to
if sort_by:
params['sortBy'] = sort_by
if direction:
params['direction'] = direction
if limit:
params['limit'] = limit
if cursor:
params['cursor'] = cursor
response = requests.get(url, headers=headers, params=params)
data = response.json()
print(f"Fetched {len(data['data'])} publications")
return data
# Fetch first page of YouTube publications
page = list_published_projects(platform='youtube', limit=25)
# Fetch next page
next_cursor = page.get('pagination', {}).get('nextCursor')
if next_cursor:
next_page = list_published_projects(
platform='youtube',
limit=25,
cursor=next_cursor
)
{
"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"
}
}
{
"data": [],
"pagination": {
"nextCursor": null
}
}
API Reference
List Published Projects
List your published posts with optional platform, profile, and date-range filtering, sorting, and cursor-based pagination, including per-platform status, analytics, and aggregated totals
GET
/
v1
/
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"
const listPublishedProjects = async ({
platform,
profileId,
from,
to,
sortBy,
direction,
limit,
cursor,
} = {}) => {
const params = new URLSearchParams();
if (platform) params.set("platform", platform);
if (profileId) params.set("profileId", profileId);
if (from) params.set("from", from);
if (to) params.set("to", to);
if (sortBy) params.set("sortBy", sortBy);
if (direction) params.set("direction", direction);
if (limit) params.set("limit", String(limit));
if (cursor) params.set("cursor", cursor);
const response = await fetch(
`https://api.submagic.co/v1/projects/published?${params}`,
{
headers: {
"x-api-key": "sk-your-api-key-here",
},
}
);
const data = await response.json();
console.log(`Fetched ${data.data.length} publications`);
return data;
};
// Fetch first page of YouTube publications
const page = await listPublishedProjects({ platform: "youtube", limit: 25 });
// Fetch next page
if (page.pagination.nextCursor) {
const nextPage = await listPublishedProjects({
platform: "youtube",
limit: 25,
cursor: page.pagination.nextCursor,
});
}
import requests
def list_published_projects(platform=None, profile_id=None, date_from=None,
date_to=None, sort_by=None, direction=None,
limit=None, cursor=None):
url = 'https://api.submagic.co/v1/projects/published'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
params = {}
if platform:
params['platform'] = platform
if profile_id:
params['profileId'] = profile_id
if date_from:
params['from'] = date_from
if date_to:
params['to'] = date_to
if sort_by:
params['sortBy'] = sort_by
if direction:
params['direction'] = direction
if limit:
params['limit'] = limit
if cursor:
params['cursor'] = cursor
response = requests.get(url, headers=headers, params=params)
data = response.json()
print(f"Fetched {len(data['data'])} publications")
return data
# Fetch first page of YouTube publications
page = list_published_projects(platform='youtube', limit=25)
# Fetch next page
next_cursor = page.get('pagination', {}).get('nextCursor')
if next_cursor:
next_page = list_published_projects(
platform='youtube',
limit=25,
cursor=next_cursor
)
{
"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"
}
}
{
"data": [],
"pagination": {
"nextCursor": null
}
}
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 atotals rollup aggregated across the post’s platforms.
This endpoint requires authentication.
Authentication
string
required
Your Submagic API key starting with
sk-Query Parameters
string
Filter by platform. Allowed values:
youtube, tiktok, instagram,
twitter, facebook, linkedin.string
Filter to a single profile (UUID). Copy the id from the Copy profile ID
action in the publishing dashboard’s profile selector.
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.string
Sort field. Allowed values:
publishedAt, views, engagement. Defaults to
publishedAt. views and engagement sort by the aggregated totals.string
Sort direction:
asc or desc. Defaults to desc.number
Number of items to return per page (1-100). Defaults to
25.string
Cursor for pagination. Pass the
nextCursor value from a previous response
to fetch the next page of results.Response
array
Array of publication objects
Hide Publication Object
Hide Publication Object
string
Unique identifier of the publication
string
The unique identifier of the underlying project
string
ISO 8601 timestamp of when the publication was published or is scheduled
to publish
boolean
true if the publication was scheduled for a future timestring
Overall publication status:
published, scheduled, processing, or
failedobject
Metrics aggregated across the publication’s platforms
array
Array of per-platform post objects
Show Post Object
Show Post Object
string
Platform identifier:
youtube, tiktok, instagram, twitter,
facebook, or linkedinstring
The post ID assigned by the upstream platform
string
Public URL of the post on the platform
string
Per-platform delivery status:
published, scheduled, processing,
or failedstring
Analytics sync status:
synced, pending, or failedstring
Error message if the post failed to publish, otherwise
nullobject
Cursor-based pagination metadata
Hide Pagination
Hide Pagination
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"
const listPublishedProjects = async ({
platform,
profileId,
from,
to,
sortBy,
direction,
limit,
cursor,
} = {}) => {
const params = new URLSearchParams();
if (platform) params.set("platform", platform);
if (profileId) params.set("profileId", profileId);
if (from) params.set("from", from);
if (to) params.set("to", to);
if (sortBy) params.set("sortBy", sortBy);
if (direction) params.set("direction", direction);
if (limit) params.set("limit", String(limit));
if (cursor) params.set("cursor", cursor);
const response = await fetch(
`https://api.submagic.co/v1/projects/published?${params}`,
{
headers: {
"x-api-key": "sk-your-api-key-here",
},
}
);
const data = await response.json();
console.log(`Fetched ${data.data.length} publications`);
return data;
};
// Fetch first page of YouTube publications
const page = await listPublishedProjects({ platform: "youtube", limit: 25 });
// Fetch next page
if (page.pagination.nextCursor) {
const nextPage = await listPublishedProjects({
platform: "youtube",
limit: 25,
cursor: page.pagination.nextCursor,
});
}
import requests
def list_published_projects(platform=None, profile_id=None, date_from=None,
date_to=None, sort_by=None, direction=None,
limit=None, cursor=None):
url = 'https://api.submagic.co/v1/projects/published'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
params = {}
if platform:
params['platform'] = platform
if profile_id:
params['profileId'] = profile_id
if date_from:
params['from'] = date_from
if date_to:
params['to'] = date_to
if sort_by:
params['sortBy'] = sort_by
if direction:
params['direction'] = direction
if limit:
params['limit'] = limit
if cursor:
params['cursor'] = cursor
response = requests.get(url, headers=headers, params=params)
data = response.json()
print(f"Fetched {len(data['data'])} publications")
return data
# Fetch first page of YouTube publications
page = list_published_projects(platform='youtube', limit=25)
# Fetch next page
next_cursor = page.get('pagination', {}).get('nextCursor')
if next_cursor:
next_page = list_published_projects(
platform='youtube',
limit=25,
cursor=next_cursor
)
{
"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"
}
}
{
"data": [],
"pagination": {
"nextCursor": null
}
}
Error Responses
object
{
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{
"field": "platform",
"message": "Must be one of: youtube, tiktok, instagram, twitter, facebook, linkedin",
"value": "snapchat"
}
]
}
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"
}
⌘I

