List Posts

GET

/posts

Retrieves a paginated list of posts from your workspace. This endpoint allows you to filter posts by various criteria including stage, type, profiles, labels, date range, and search terms. Use this to manage your content calendar, track post statuses, and retrieve post details for scheduling and publishing.

Notes

By default, posts with stage ARCHIVE are excluded from results unless explicitly requested in the stages parameter.

Network-specific objects (facebook, instagram, linkedIn, tiktok) only appear in the response when the post is configured for those networks.

Posts can have different captions and media for different social networks - check the net property in each array item.

The publishStatus field on each profile indicates the publishing status for that specific profile if already in publishing process.

Post stages follow a workflow: IDEA → DRAFT → TEAM_REVIEW → TEAM_APPROVED → SCHEDULED → PUBLISHED.

Request

Query Params

Header Params

Responses

🟢200

application/json

Bodyapplication/json

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.swonkie.dev/v2/posts?skip=0&take=20&since=2026-01-01&until=2026-01-31&stages=IDEA%2CDRAFT%2CSCHEDULED&types=MEDIA%2CLINK&profileIds=Tjg3YjhSU2xZREFqM1RqOTRnZTdpZz09%2CRDlHZERwbitlK1lmQU0xNW0zWUhWZz09&labelIds=QWJjMTIzRGVmNDU2&search=product%20launch' \
--header 'X-API-ID: ' \
--header 'X-API-KEY: '

Response Example

{
    "items": [
        {
            "id": "UG9zdElkMTIzNDU2Nzg5",
            "type": "MEDIA",
            "stage": "SCHEDULED",
            "publishAt": "2026-02-01T10:00:00.000Z",
            "budget": 0,
            "profiles": [
                {
                    "id": "Tjg3YjhSU2xZREFqM1RqOTRnZTdpZz09",
                    "name": "Brand Official Page",
                    "username": "brandofficial",
                    "picture": "https://storage.example.com/profiles/abc123.jpg",
                    "net": {
                        "code": "facebook",
                        "name": "Facebook"
                    },
                    "publishStatus": "PENDING"
                }
            ],
            "captions": [
                {
                    "plainText": "Excited to announce our new product! 🚀 #innovation",
                    "net": {
                        "name": "Facebook",
                        "code": "facebook"
                    },
                    "firstComment": {
                        "plainText": "Tell us what you think in the comments!"
                    }
                }
            ],
            "medias": [
                {
                    "id": "TWVkaWFJZDk4NzY1NDMyMQ==",
                    "url": "https://storage.example.com/media/product.jpg",
                    "type": "image/jpeg",
                    "net": {
                        "name": "Facebook",
                        "code": "facebook"
                    }
                }
            ],
            "links": [],
            "labels": [
                {
                    "id": "TGFiZWxJZDExMTExMTEx",
                    "name": "Marketing Campaign",
                    "color": "#FF5733"
                }
            ],
            "briefing": {
                "markdown": "# Campaign Brief\n\nThis is a major product launch..."
            }
        }
    ],
    "total": 45,
    "skip": 0,
    "take": 20
}

Modified at 2026-06-19 17:25:23

Limits by Social Network

Get a Post

List Posts

Notes#

Request

Responses

Notes