Skip to main content
GET
/
api
/
partner
/
v1
/
posts
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/posts?status=scheduled&limit=20' \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Posts retrieved",
  "data": {
    "summary": {
      "total": 193,
      "pending": 58,
      "published": 120,
      "by_status": {
        "draft": 15,
        "pending": 12,
        "scheduled": 46,
        "posted": 118,
        "failed": 4
      }
    },
    "posts": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "caption": "Holiday drops start Monday!",
        "status": "deleted",
        "scheduled_at": "2025-02-01T15:00:00Z",
        "created_at": "2025-01-20T12:05:11.205Z",
        "media": {
          "type": "video",
          "url": "https://cdn.example.com/video.mp4"
        },
        "music_url": null,
        "tiktok": null,
        "pinterest": {
          "board_id": "123456789012345678",
          "title": "Dinner board",
          "tags": ["Italian recipes"]
        },
        "accounts": {
          "total": 2,
          "states": [
            {
              "account_id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
              "status": "deleted",
              "published_at": null,
              "error_message": null,
              "last_attempted_at": null,
              "published_url": null
            },
            {
              "account_id": "6b0c8c9c-55ac-4fcb-85ec-70b5a8b0d089",
              "status": "scheduled",
              "published_at": null,
              "error_message": null,
              "last_attempted_at": null,
              "published_url": null
            }
          ]
        }
      }
    ]
  }
}
Fetch the latest posts in key scope along with a summary. Use this to track delivery status for posts across TikTok, Instagram, YouTube, Pinterest, LinkedIn, and Facebook - including posts scheduled by your OpenClaw agent or automation scripts.
Only posts that include deliveries for accounts owned by the authenticated key scope are returned. Hosted and BYO accounts are both supported, and deliveries for accounts outside scope are filtered out automatically.

​
Query Parameters

​
status
string
Filter by status: draft, pending, scheduled, posted, failed, partial, retry. When omitted, all statuses are returned.
​
limit
number
default:"20"
Number of posts to return. Values below 1 are treated as 1; values above 100 are clamped to 100.
​
since
string
ISO timestamp. Only include posts created on or after this time.
​
until
string
ISO timestamp. Only include posts created on or before this time.
since and until must be valid ISO 8601 strings. Invalid values return a 400 response with error_code set to invalid_since or invalid_until.

​
Response

Returns a summary object with counts and a posts array.
​
summary
object
Scope-wide counters.
​
posts
array
List of post objects. Each post may include tiktok and/or pinterest settings when those platform-specific payloads were provided at create/update time.
summary.by_status tracks canonical lifecycle buckets (draft, pending, scheduled, posted, partial, failed). Provider-facing statuses (for example deleted/void) can still appear on individual post/account status fields and are included in summary.total.
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/posts?status=scheduled&limit=20' \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Posts retrieved",
  "data": {
    "summary": {
      "total": 193,
      "pending": 58,
      "published": 120,
      "by_status": {
        "draft": 15,
        "pending": 12,
        "scheduled": 46,
        "posted": 118,
        "failed": 4
      }
    },
    "posts": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "caption": "Holiday drops start Monday!",
        "status": "deleted",
        "scheduled_at": "2025-02-01T15:00:00Z",
        "created_at": "2025-01-20T12:05:11.205Z",
        "media": {
          "type": "video",
          "url": "https://cdn.example.com/video.mp4"
        },
        "music_url": null,
        "tiktok": null,
        "pinterest": {
          "board_id": "123456789012345678",
          "title": "Dinner board",
          "tags": ["Italian recipes"]
        },
        "accounts": {
          "total": 2,
          "states": [
            {
              "account_id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
              "status": "deleted",
              "published_at": null,
              "error_message": null,
              "last_attempted_at": null,
              "published_url": null
            },
            {
              "account_id": "6b0c8c9c-55ac-4fcb-85ec-70b5a8b0d089",
              "status": "scheduled",
              "published_at": null,
              "error_message": null,
              "last_attempted_at": null,
              "published_url": null
            }
          ]
        }
      }
    ]
  }
}

​
Error Responses

  • 400 invalid_since or 400 invalid_until - query params failed ISO parsing
  • 401 - authentication failed (missing/invalid/revoked token)
  • 402 subscription_required - active Creator/Professional/Business plan required
  • 403 tier_not_allowed - Scheduler tier cannot use Partner API
  • 500 list_failed - Database query or summary computation failed