Curator API: Get Posts
GET https://api.curator.io/v1/feeds/FEED_ID/posts returns the posts in a feed as JSON, so you can render them yourself or pipe them into another system. The endpoint is public and needs no API key; supplying your API key only adds source_id, feed_id, and last_modified to each post. Only HTTPS is supported.
Authentication
The endpoint works without a key. To get the private fields on each post, send your Curator API key (find it in the Curator Dashboard) in one of three ways: as a query string (?api_key=API_KEY), as a Basic auth header with the API key as the username, or as a Bearer token (Authorization: Bearer API_KEY).
Example request
curl "https://api.curator.io/v1/feeds/FEED_ID/posts?limit=25"Parameters
Parameter | Description |
|---|---|
| The feed's API ID (a UUID) or its public key. A feed that does not exist returns 404. |
| Number of posts to return, between 1 and 100. Default 100. Invalid or out-of-range values fall back to the default. |
| Number of posts to skip before the first returned post. Default 0. Ignored when |
| Cursor from a previous response's |
| Cursor from a previous response's |
| Only posts whose |
|
|
| Post status filter. Default |
| Only posts whose |
| Only posts whose |
| Only posts from this network. Pass |
| Only posts from these sources, as a comma-separated list of source IDs. Pass |
| Only posts of this source type. Pass |
| Pass |
| Pass |
| Only posts updated after this timestamp (compares against the post's |
| Only posts created on or after this date (compares against |
| Only posts created on or before this date (compares against |
| Location filter: only posts tagged with a location within |
| Include paused ads in the |
| Your Curator API key. May also be sent as a Basic auth header with the API key as the username, or as a Bearer token. With a valid key, each post includes |
Response
A 200 response contains the posts for one page plus feed metadata:
{
"success": true,
"cache": { "status": "miss", "key": "/v1/feeds/FEED_ID/posts", "time": 5 },
"pagination": {
"after": "eyJwaW5uZWQiOjAsInNvdXJjZV9jcmVhdGVkX2F0IjoiMjAyMy0wOS0yMVQwMDo0NTozNy4wMDAwMDAwMDAwWiJ9",
"before": "eyJwaW5uZWQiOjAsInNvdXJjZV9jcmVhdGVkX2F0IjoiMjAyNC0xMi0wNVQwMToyNjozMy4wMDAwMDAwMDAwWiJ9"
},
"networks": [2, 3],
"sources": [
{ "name": "@curatoruser", "id": 228698, "network_id": 2 },
{ "name": "Golden Retrievers", "id": 228699, "network_id": 3 }
],
"postCount": 1,
"posts": [ { ... } ],
"ads": []
}Field | Description |
|---|---|
| Always true on a successful response. |
| Cursor pagination for the default sort. Empty when the result set has no posts; cursor fields are omitted when |
| The network IDs of the feed's sources, deduplicated. |
| The feed's sources, each with |
| Total number of matching posts, counted before pagination. Always 0 when a location filter is active. |
| The posts for this page. See the post object below. |
| Ads defined for the feed. Paused ads are excluded unless |
| Cache metadata. |
Post object
Boolean-style flags are integers, 0 for no and 1 for yes.
Field | Description |
|---|---|
| Post ID. |
| ID of the network the post came from. |
| Network name, such as Instagram or Facebook. |
| Post status code and status name, such as 1 and |
| Whether the post is flagged. |
| Source type ID and the post's identifier on its source network. |
| When the post was created on its source network. |
| Post text, and whether that text contains HTML. |
| Handle and display name of the post's author. |
| URLs of the author's profile image and profile. |
| URL of the post's image. Empty when the post has no image. |
| Larger versions of the image. |
| Width and height of the post image in pixels. |
| Media flags for the post. |
| Image carousel entries, when the post has multiple images. Each entry has |
| Video fields. |
| Link to the original post. |
| Engagement counts on the source network. |
| Post type flags. |
| Original author and post details when the post is a repost. |
| Whether the post is pinned in the feed, and when. |
| Location data, when the post is tagged with one. |
| Dimensions of the large image version. |
| Soft-delete timestamp, when set. |
| Additional payload arrays. |
| Source UUID, feed UUID, and when the post was last updated in Curator. Only present when the request is authenticated with an API key. |
Paginating with cursors
With the default sort, each response includes pagination.after and pagination.before cursors (Base64-encoded strings). Pass after to fetch the next, older page:
const res = await fetch(`https://api.curator.io/v1/feeds/${feedId}/posts?limit=50`);
const data = await res.json();
const nextUrl = `https://api.curator.io/v1/feeds/${feedId}/posts?limit=50&after=${encodeURIComponent(data.pagination.after)}`;before returns posts newer than the cursor, but always starts from the newest post in the feed. It only lands on the previous page when you are on the second page. To move back further, keep the URLs of the pages you already fetched and request them again. after wins when both cursors are sent, and both win over since and offset. Cursors are only available with the default sort; sort_by=last_modified responses have no cursor fields.
A cursor that cannot be decoded is ignored without an error, and the response starts from the first page. Posts that share the same pinned value and source_created_at as the last post on a page can be skipped by the next page.
Errors
Status | When | Body |
|---|---|---|
404 | No feed exists for the supplied feed ID. |
|
429 | When rate limiting is enabled, more than 300 requests per minute. |
|
Aliases
GET https://api.curator.io/v1/feeds/FEED_ID and GET https://api.curator.io/v1/feed/FEED_ID/posts return the same response as GET https://api.curator.io/v1/feeds/FEED_ID/posts.