Publishing · Posts

List posts

Returns posts, one page at a time.

GEThttps://api.pozy.ai/v1/posts

listPosts

Guides: External posts, Post lifecycle, Scheduling and timezones

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the publishing resource group disabled get 403 resource_group_disabled. Authentication

Query parameters

Name	Type	Notes
`page`	integer	Default `1`At least 1
`limit`	integer	Default `10`1 to 500
`offset`	integer	At least 0
`cursor`	string
`fields`	string
`updatedSince`	string (date-time)
`source`	string	One of `pozy`, `external`Default `pozy`
`status`	string	One of `draft`, `pending_approval`, `scheduled`, `publishing`, `published`, `partial`, `failed`, `cancelled`
`platform`	string
`profileId`	string
`createdBy`	string
`fromDate`	string (date)
`toDate`	string (date)
`dateFrom`	string (date)
`dateTo`	string (date)
`includeHidden`	boolean	Default `false`
`search`	string
`tags`	string
`sortBy`	string	One of `scheduled-desc`, `scheduled-asc`, `created-desc`, `created-asc`, `status`, `platform`Default `scheduled-desc`
`accountId`	string

Example

curl -X GET "https://api.pozy.ai/v1/posts?limit=10" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/posts?limit=10", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "limit": 10,
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

postsarray of object
20 child fields
- _idstring
- userIdstring or object
  One of:
  string
  User (6 fields)
  _idstring
  emailstring
  namestring
  rolestring
  disabledResourceGroupsarray of string
  createdAtstring (date-time)
- titlestring
- contentstring
- mediaItemsarray of object
  13 child fields
  typestring
  One of image, video, gif, document.
  urlstring (URL)
  fileIdstring
  accountIdstring
  titlestring
  altTextstring
  filenamestring
  sizeinteger
  mimeTypestring
  thumbnailstring (URL)
  instagramThumbnailstring (URL)
  subtitlesarray of object
  Up to 20 items.
  2 child fields
  urlstring (URL)required
  languagestringrequired
  tiktokProcessedboolean
- platformsarray of object
  19 child fields
  platformstring
  accountIdstring or object
  One of:
  string
  Social Account (19 fields)
  _idstringrequired
  platformstringrequired
  One of tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, slack, whatsapp, shopify, wordpress, wix, linkedinads, metaads, pinterestads, tiktokads, xads and 15 more.
  profileIdstring or objectrequired
  One of:
  string
  Profile (11 fields)
  _idstring
  userIdstring
  namestring
  descriptionstring
  colorstring
  timezonestring
  Can be null.
  externalIdstring
  Can be null.
  isDefaultboolean
  isOverLimitboolean
  accountCountinteger
  createdAtstring (date-time)
  usernamestring
  displayNamestring
  platformUserIdstring
  scopeAreasarray of string
  Can be null.
  oauthAppIdstring
  Can be null.
  tiktokAccountTypestring
  One of business, personal, unknown.
  profilePicturestring
  Can be null.
  profileUrlstring
  isActivebooleanrequired
  needsReconnectionboolean
  followersCountnumber
  followersLastUpdatedstring (date-time)
  parentAccountIdstring
  Can be null.
  enabledboolean
  rateLimitedUntilstring (date-time)
  Can be null.
  metadataobject
  customContentstring
  customMediaarray of object
  13 child fields
  typestring
  One of image, video, gif, document.
  urlstring (URL)
  fileIdstring
  accountIdstring
  titlestring
  altTextstring
  filenamestring
  sizeinteger
  mimeTypestring
  thumbnailstring (URL)
  instagramThumbnailstring (URL)
  subtitlesarray of object
  Up to 20 items.
  2 child fields
  urlstring (URL)required
  languagestringrequired
  tiktokProcessedboolean
  scheduledForstring (date-time)
  platformSpecificDataobject
  statusstring
  platformPostIdstring
  platformPostUrlstring
  Can be null.
  publishedAtstring (date-time)
  removedFromPlatformAtstring (date-time)
  Can be null.
  isTrialReelboolean
  trialGraduationStrategystring
  One of MANUAL, SS_PERFORMANCE.
  publishAttemptsinteger
  publishRetriesinteger
  errorMessagestring
  errorCategorystring
  One of auth_expired, user_content, user_abuse, account_issue, platform_rejected, platform_error, platform_rate_limit, quota_exhausted, system_error, unknown.
  errorSourcestring
  One of user, platform, system.
  platformErrorobject
  3 child fields
  codeinteger
  subcodeinteger
  messagestringrequired
- scheduledForstring (date-time)
- timezonestring
- statusstring
  One of draft, pending_approval, scheduled, publishing, published, partial, failed, cancelled.
- tagsarray of string
- hashtagsarray of string
- mentionsarray of string
- visibilitystring
  One of public, private, unlisted.
- metadataobject
- recyclingobject
  11 child fields
  enabledboolean
  gapinteger
  gapFreqstring
  One of week, month.
  startDatestring (date-time)
  expireCountinteger
  expireDatestring (date-time)
  contentVariationsarray of string
  contentVariationIndexinteger
  recycleCountinteger
  nextRecycleAtstring (date-time)
  lastRecycledAtstring (date-time)
- recycledFromPostIdstring
- queuedFromProfilestring
- queueIdstring
- createdAtstring (date-time)
- updatedAtstring (date-time)
paginationobject
- pageinteger
- limitinteger
- totalinteger
- pagesinteger
- nextCursorstring
  Can be null.

200 response

{
  "posts": [
    {
      "_id": "635d87e261ae344ef27fd1df",
      "userId": "6da95b9455a22c1e061837af",
      "title": "Launch day",
      "content": "Hello from Pozy",
      "mediaItems": [
        {
          "type": "image",
          "url": "https://pozy.ai/media/example-1.jpg",
          "fileId": "6035bf6bd3aac3067c336c50",
          "accountId": "696e0b682d0a31188e7a2ba9",
          "title": "Launch day",
          "altText": "Hello from Pozy",
          "filename": "photo.jpg",
          "size": 482133,
          "mimeType": "image/jpeg",
          "thumbnail": "https://pozy.ai/media/example-1.jpg",
          "instagramThumbnail": "https://pozy.ai/media/example-1.jpg",
          "subtitles": [
            {
              "url": "https://pozy.ai/media/example-1.jpg",
              "language": "en"
            }
          ],
          "tiktokProcessed": true
        }
      ],
      "platforms": [
        {
          "platform": "instagram",
          "accountId": "696e0b682d0a31188e7a2ba9",
          "customContent": "Hello from Pozy",
          "customMedia": [
            {
              "type": "image",
              "url": "https://pozy.ai/media/example-1.jpg",
              "fileId": "6035bf6bd3aac3067c336c50",
              "accountId": "696e0b682d0a31188e7a2ba9",
              "title": "Launch day",
              "altText": "Hello from Pozy",
              "filename": "photo.jpg",
              "size": 482133,
              "mimeType": "image/jpeg",
              "thumbnail": "https://pozy.ai/media/example-1.jpg",
              "instagramThumbnail": "https://pozy.ai/media/example-1.jpg",
              "subtitles": [
                {}
              ],
              "tiktokProcessed": true
            }
          ],
          "scheduledFor": "2026-10-02T09:00:00.000Z",
          "platformSpecificData": {},
          "status": "active",
          "platformPostId": "637f799b3039e6602e83fa4f",
          "platformPostUrl": "https://pozy.ai/media/example-1.jpg",
          "publishedAt": "2026-10-02T09:00:00.000Z",
          "removedFromPlatformAt": "2026-10-02T09:00:00.000Z",
          "isTrialReel": true,
          "trialGraduationStrategy": "MANUAL",
          "publishAttempts": 1,
          "publishRetries": 1,
          "errorMessage": "Hello from Pozy",
          "errorCategory": "auth_expired",
          "errorSource": "user",
          "platformError": {
            "code": 1,
            "subcode": 1,
            "message": "Hello from Pozy"
          }
        }
      ],
      "scheduledFor": "2026-10-02T09:00:00.000Z",
      "timezone": "America/New_York",
      "status": "draft",
      "tags": [
        "string"
      ],
      "hashtags": [
        "string"
      ],
      "mentions": [
        "string"
      ],
      "visibility": "public",
      "metadata": {},
      "recycling": {
        "enabled": true,
        "gap": 1,
        "gapFreq": "week",
        "startDate": "2026-10-02T09:00:00.000Z",
        "expireCount": 42,
        "expireDate": "2026-10-02T09:00:00.000Z",
        "contentVariations": [
          "Hello from Pozy"
        ],
        "contentVariationIndex": 1,
        "recycleCount": 42,
        "nextRecycleAt": "2026-10-02T09:00:00.000Z",
        "lastRecycledAt": "2026-10-02T09:00:00.000Z"
      },
      "recycledFromPostId": "6786dd4f9a1815d922da3579",
      "queuedFromProfile": "string",
      "queueId": "6a5f84bc69bcee401578bb47",
      "createdAt": "2026-10-02T09:00:00.000Z",
      "updatedAt": "2026-10-02T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 42,
    "pages": 1,
    "nextCursor": "string"
  }
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is scoped to other profiles or has this resource group disabled.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

Request

Query parameters

Example

Response

Errors

More in Posts