Curator API: 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) either as a query string (?api_key=API_KEY) or as a Basic auth header with the API key as the username.

Example request

curl "https://api.curator.io/v1/feeds/FEED_ID/posts?limit=25"

Parameters

Parameter	Description
`feed_id` (path)	The feed's API key or public key. A feed that does not exist returns 404.
`limit`	Number of posts to return, between 1 and 100. Default 100. Invalid or out-of-range values fall back to the default.
`offset`	Number of posts to skip before the first returned post. Default 0. Ignored when `after`, `before`, or `since` is supplied.
`after`	Cursor from a previous response's `pagination.after`. Returns posts older than the cursor position.
`before`	Cursor from a previous response's `pagination.before`. Returns posts newer than the cursor position. Ignored when `after` is also supplied.
`since`	Only posts whose `source_created_at` is later than this value. Ignored when `after` or `before` is supplied.
`sort_by`	`default` (the default): pinned posts first, then newest posts first. `last_modified`: most recently updated posts first. Cursor pagination is only available with `default`.
`status`	Post status filter. Default `approved` (approved posts only). Pass `all` for approved and needs-approval posts, `1` for approved only, `0` for needs-approval only, or a comma-separated list of status names.
`username`	Only posts whose `user_full_name` or `user_screen_name` contains this value, case-insensitively.
`text`	Only posts whose `text` contains this value.
`network_id`	Only posts from this network. Pass `all` to disable the filter.
`source_id`	Only posts from these sources, as a comma-separated list of source IDs. Pass `all` to disable the filter.
`source_type`	Only posts of this source type. Pass `all` to disable the filter.
`is_image`	Only posts that have an image (`1`) or no image (`0`).
`is_video`	Only posts that have a video (`1`) or no video (`0`).
`last_modified`	Only posts updated after this timestamp (compares against the post's `updated_at`).
`date_from`	Only posts created on or after this date (compares against `source_created_at`).
`date_to`	Only posts created on or before this date (compares against `source_created_at`).
`longitude`, `latitude`, `distance`	Location filter: only posts tagged with a location within `distance` of the given point. All three are required together. When this filter is active, `postCount` is always 0.
`showPausedAds`	Include paused ads in the `ads` array. By default only active ads are returned.
`api_key`	Your Curator API key. May also be sent as a Basic auth header with the API key as the username. With a valid key, each post includes `source_id`, `feed_id`, and `last_modified`.

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
`success`	Always true on a successful response.
`pagination`	Cursor pagination for the default sort. Empty when the result set has no posts; cursor fields are omitted when `sort_by` is `last_modified`.
`networks`	The network IDs of the feed's sources, deduplicated.
`sources`	The feed's sources, each with `name`, `id`, and `network_id`.
`postCount`	Total number of matching posts, counted before pagination. Always 0 when a location filter is active.
`posts`	The posts for this page. See the post object below.
`ads`	Ads defined for the feed. Paused ads are excluded unless `showPausedAds` is supplied.
`cache`	Cache metadata: `status` (`hit` or `miss`), `key`, and `time`.

Post object

Boolean-style flags are integers, 0 for no and 1 for yes.

Field	Description
`id`	Post ID.
`network_id`	ID of the network the post came from.
`network_name`	Network name, such as Instagram or Facebook.
`status` / `post_status`	Post status code and status name, such as 1 and `approved`.
`flagged`	Whether the post is flagged.
`source_type` / `source_identifier`	Source type ID and the post's identifier on its source network.
`source_created_at`	When the post was created on its source network.
`text` / `is_html`	Post text, and whether that text contains HTML.
`user_screen_name` / `user_full_name`	Handle and display name of the post's author.
`user_image` / `user_url`	URLs of the author's profile image and profile.
`image`	URL of the post's image. Empty when the post has no image.
`image_large` / `image_xlarge`	Larger versions of the image. `image_large` falls back to `image` when no larger version exists; `image_xlarge` is always set.
`image_width` / `image_height`	Width and height of the post image in pixels.
`has_image` / `has_video` / `has_media` / `image_processed`	Media flags for the post.
`images`	Image carousel entries, when the post has multiple images. Each entry has `url`, `width`, and `height`.
`video` / `video_width` / `video_height` / `thumbnail`	Video fields. `video` is empty when the post has no video.
`url`	Link to the original post.
`comments` / `views` / `likes`	Engagement counts on the source network.
`is_repost` / `is_reply` / `is_edited` / `is_embed`	Post type flags.
`originator_user_screenname` / `originator_user_url` / `originator_post_url`	Original author and post details when the post is a repost.
`pinned` / `pinned_at`	Whether the post is pinned in the feed, and when.
`longitude` / `latitude` / `location_name`	Location data, when the post is tagged with one.
`image_large_width` / `image_large_height`	Dimensions of the large image version.
`deleted_at`	Soft-delete timestamp, when set.
`data` / `media` / `spots`	Additional payload arrays.
`source_id` / `feed_id` / `last_modified`	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 moves the other way. 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.

Errors

Status	When	Body
404	No feed exists for the supplied feed ID.	`{"message": "Feed FEED_ID was not found", "code": 404, "error": true}`
429	When rate limiting is enabled, more than 300 requests per minute.	`{"message": "Too Many Attempts."}`

Aliases

GET /v1/feeds/{feed_id} and GET /v1/feed/{feed_id}/posts return the same response as GET /v1/feeds/{feed_id}/posts.

Was this helpful?