List Published Posts

List your published posts, filtered by text and platform, with each post's latest analytics snapshot attached. Use this to find a published post and its id, or to browse recent posts with their current metrics.

For engagement rankings and full metric history, see Analytics.

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /published-posts

Method: GET

Description

Returns your published posts, newest or oldest first, filtered by an optional full-text query and platform. Each item carries its latest metrics snapshot. Results use offset-based pagination with a total count.

Query Parameters

Field	Type	Required	Description
query	string	No	Full-text search over post content. Omit to include all posts.
platform	string	No	Filter to one platform. Omit to include all platforms.
sortBy	string	No	Sort order: newest or oldest. Default newest.
offset	integer	No	Number of posts to skip before the page. Default 0.
limit	integer	No	Number of posts to return. Min: 1, Max: 100. Default: 20.

Response

Status Code: 200 OK

{
  "items": [
    {
      "id": "98431",
      "content": "Check out this image!",
      "postUrl": "https://instagram.com/p/abc123",
      "platform": "instagram",
      "createdAt": "2026-05-30T09:15:00.000Z",
      "mediaUrls": ["https://example.com/image1.jpg"],
      "latestMetrics": {
        "fetchedAt": "2026-06-11T12:00:00.000Z",
        "metrics": { "likesCount": "1240", "reachCount": "53000" }
      },
      "metricsHistory": []
    }
  ],
  "count": 137
}

Field	Type	Description
items	array	Published posts for this page.
items[].id	string	The published post id. Pass it to Get Post Analytics for full metric history.
items[].content	string	The post text.
items[].postUrl	string or null	Live URL of the published post. Null if the platform did not return one.
items[].platform	string	Social media platform.
items[].createdAt	string	ISO 8601 timestamp when the post was published.
items[].mediaUrls	string[]	URLs of attached media. Empty when text-only.
items[].latestMetrics	object	The most recent metrics snapshot. Absent if no metrics have been collected yet. See Metrics.
items[].metricsHistory	array	Collected snapshots, oldest first. Each is { fetchedAt, metrics }.
count	integer	Total number of posts matching your search, across all pages.

To page through results, increase offset by limit on each call until offset reaches count.

Errors

Status	Reason
422	Invalid sortBy, offset, or limit value.

Example

GET https://backend.blotato.com/v2/published-posts?query=summer&platform=instagram&limit=20 HTTP/1.1
blotato-api-key: YOUR_API_KEY