REST API

The Feedframer REST API returns an Instagram account's profile and posts as JSON. This page is the reference for every endpoint, parameter and response field.

Base URL

https://feedframer.com

All REST endpoints live under /api/v1.

Authentication

Every request needs your API key in the api_key query parameter. Headers are not read.

?api_key=YOUR_API_KEY

Each connected Instagram account has its own key. You'll find it on the Dashboard, on the account's card, labelled "Feedframer API Token". A key only ever reads its own account. See Authentication for regenerating and revoking keys.

Endpoints

There is no /api/v1/posts endpoint. Posts come from /api/v1/me. Any other path under /api/ returns a 404 with the code NOT_FOUND.

GET /api/v1/me

Returns the profile of the account that owns the key, with its posts nested in a posts array.

Parameters

All parameters go in the query string. Only api_key is required.

There is no parameter to choose an account. The key decides which account you get.

Square brackets in query strings trip up some tools. With curl, pass -g (or URL-encode the brackets as %5B and %5D). A + in a time zone offset must be sent as %2B, or it arrives as a space and fails validation.

Free and Premium

On Free, filters and sorting apply within those 6 most recent posts. For example, filter[type]=VIDEO returns only the videos among the latest 6, which may be none. sort=published_at returns the same 6 posts, oldest first. The pagination object on a free key always has nextCursor: null, prevCursor: null and hasMore: false.

The limits are set per plan on the pricing page.

Example request

curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&filter[type]=IMAGE'

This returns the image posts, newest first, up to your plan's page size.

Example response

{
  "username": "your_username",
  "name": "Your Name",
  "biography": "Your bio text",
  "website": "https://example.com",
  "profilePictureUrl": "https://cdn.feedframer.com/your_username/123_profile.jpg",
  "followersCount": 1234,
  "followsCount": 567,
  "mediaCount": 89,
  "status": "ready",
  "lastFetchAt": "2026-01-15T19:50:34+00:00",
  "posts": [
    {
      "id": "18123456789012345",
      "caption": "Sunset over the harbour #photography",
      "altText": null,
      "mediaType": "IMAGE",
      "mediaUrl": "https://cdn.feedframer.com/your_username/18123456789012345_media.jpg",
      "thumbnailUrl": null,
      "permalink": "https://www.instagram.com/p/ABC123def45/",
      "timestamp": "2026-01-15T18:30:00+00:00",
      "likeCount": 1542,
      "commentsCount": 87,
      "sizes": {
        "320": "https://cdn.feedframer.com/cdn-cgi/image/width=320,format=jpg/your_username/18123456789012345_media.jpg",
        "768": "https://cdn.feedframer.com/cdn-cgi/image/width=768,format=jpg/your_username/18123456789012345_media.jpg",
        "960": "https://cdn.feedframer.com/cdn-cgi/image/width=960,format=jpg/your_username/18123456789012345_media.jpg",
        "1200": "https://cdn.feedframer.com/cdn-cgi/image/width=1200,format=jpg/your_username/18123456789012345_media.jpg"
      }
    }
  ],
  "pagination": {
    "nextCursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDI2LTAxLTE1IDE4OjMwOjAwIiwiaWQiOjQyLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prevCursor": null,
    "hasMore": true,
    "perPage": 100
  }
}

This is a premium response. A free response has no sizes field on posts.

Response headers

Account fields

These are at the top level of the response.

Profile fields refresh at most once a day.

Connection status

status tells you whether Feedframer is still able to reach Instagram for this account. A broken connection does not change the HTTP status code. You still get a 200 with the posts we last stored, so an existing feed keeps rendering instead of going blank — but nothing new will arrive until the account is reconnected. Check this field if you want to know.

An Instagram access token lasts 60 days, and it can also be cut short by a password change, by removing Feedframer in Instagram's app settings, or by a security checkpoint on the account. Feedframer refreshes tokens automatically and emails you if a connection breaks, but if you are rendering a feed on a live site it is worth surfacing invalid_token somewhere you will see it:

const feed = await fetch('https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY')
  .then((r) => r.json());

if (feed.status === 'invalid_token') {
  // Still render feed.posts — they are real, just not fresh.
  console.warn(`Feedframer: @${feed.username} needs reconnecting. Last updated ${feed.lastFetchAt}.`);
}

Responses are cached at the edge for an hour, so a status change can take up to an hour to appear. /api/v1/accounts returns the same status for every account on your plan.

Post fields

Each item in posts has these fields.

Don't put mediaUrl in an <img> tag for VIDEO posts. It is usually a video file. Use thumbnailUrl instead:

const imageSrc = post.mediaType === 'VIDEO' ? post.thumbnailUrl : post.mediaUrl;

Pagination fields

Cursors are opaque strings. Pass them back unchanged. See Pagination for loops in several languages.

Including extra data

include takes an array, so write it as include[]=. Plain include=children or include=children,comments returns a 422. To get both, repeat the parameter:

curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&include[]=children&include[]=comments'

Carousel items (children)

A CAROUSEL_ALBUM post's mediaUrl is only its first item. Add include[]=children to get every item:

curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&filter[type]=CAROUSEL_ALBUM&include[]=children'

Each post then has a children array. Posts that aren't carousels get "children": [].

{
  "id": "18123456789012345",
  "caption": "Three views of the harbour",
  "altText": null,
  "mediaType": "CAROUSEL_ALBUM",
  "mediaUrl": "https://cdn.feedframer.com/your_username/18123456789012345_media.jpg",
  "thumbnailUrl": null,
  "permalink": "https://www.instagram.com/p/ABC123def45/",
  "timestamp": "2026-01-15T18:30:00+00:00",
  "likeCount": 1542,
  "commentsCount": 87,
  "children": [
    {
      "id": "18111111111111111",
      "caption": null,
      "altText": null,
      "mediaType": "IMAGE",
      "mediaUrl": "https://cdn.feedframer.com/your_username/18111111111111111_media.jpg",
      "thumbnailUrl": null,
      "permalink": "https://www.instagram.com/p/XYZ789ghi01/",
      "timestamp": "2026-01-15T18:30:00+00:00",
      "likeCount": null,
      "commentsCount": null
    },
    {
      "id": "18222222222222222",
      "caption": null,
      "altText": null,
      "mediaType": "VIDEO",
      "mediaUrl": "https://cdn.feedframer.com/your_username/18222222222222222_media.mp4",
      "thumbnailUrl": "https://cdn.feedframer.com/your_username/18222222222222222_thumbnail.jpg",
      "permalink": "https://www.instagram.com/p/JKL456mno78/",
      "timestamp": "2026-01-15T18:30:00+00:00",
      "likeCount": null,
      "commentsCount": null
    }
  ]
}

This example is from a free key, so there are no sizes.

Children have the same fields as posts, so the same rendering code works for both. The differences:

• caption, altText, likeCount and commentsCount are always null. Use the parent post's values.
• Each child has its own permalink, which is not the parent's.
• mediaType is IMAGE or VIDEO. VIDEO children have a thumbnailUrl; IMAGE children have null.
• mediaUrl and thumbnailUrl always point to Feedframer's CDN. Children whose media Feedframer hasn't stored are left out of the array.
• On premium keys every child has a sizes field. It uses the thumbnail for VIDEO children, and is null for a VIDEO child with no stored thumbnail. On free keys children have no sizes field.

Comments

Add include[]=comments to get each post's comments as Instagram returned them at the last fetch:

curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&include[]=comments'

Each post then has a comments array. It is empty when there are none.

{
  "comments": [
    {
      "id": "17900000000000000",
      "text": "Love this view",
      "timestamp": "2026-01-15T19:02:11+0000",
      "like_count": 3
    }
  ]
}

Comments don't include the commenter's username.

Responsive images and format (Premium)

Premium responses include a sizes object on each post whose media Feedframer has stored. It holds URLs for the same image resized to 320, 768, 960 and 1200 pixels wide, served through Cloudflare. For VIDEO posts, they are resized copies of the thumbnail.

Add format=webp to get WebP URLs instead of JPEG:

curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&format=webp'

"sizes": {
  "320": "https://cdn.feedframer.com/cdn-cgi/image/width=320,format=webp/your_username/18123456789012345_media.jpg",
  "768": "https://cdn.feedframer.com/cdn-cgi/image/width=768,format=webp/your_username/18123456789012345_media.jpg",
  "960": "https://cdn.feedframer.com/cdn-cgi/image/width=960,format=webp/your_username/18123456789012345_media.jpg",
  "1200": "https://cdn.feedframer.com/cdn-cgi/image/width=1200,format=webp/your_username/18123456789012345_media.jpg"
}

The keys are strings. In JavaScript, use post.sizes['320']; post.sizes.320 is a syntax error. Because sizes is missing on free keys and on some posts, fall back to thumbnailUrl or mediaUrl:

function imageAttributes(post) {
  const fallback = post.mediaType === 'VIDEO' ? post.thumbnailUrl : post.mediaUrl;

  if (!post.sizes) {
    return { src: fallback };
  }

  return {
    src: post.sizes['768'],
    srcset: ['320', '768', '960', '1200']
      .map((width) => `${post.sizes[width]} ${width}w`)
      .join(', '),
  };
}

Filtering

# Image posts only
curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&filter[type]=IMAGE'

# Posts published during March 2026 (both dates included in full)
curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&filter[publishedAfter]=2026-03-01&filter[publishedBefore]=2026-03-31'

Filters can be combined. See Filtering & Sorting for every rule.

Sorting

# Oldest first
curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&sort=published_at'

id sorting uses the order Feedframer stored the posts, not the Instagram post id.

Pagination

Premium keys page through posts with cursors:

# First page, 50 posts (Premium; a free key gets its 6 posts)
curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&page[size]=50'

# Next page: pass pagination.nextCursor from the previous response
curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&page[size]=50&page[cursor]=NEXT_CURSOR'

Keep the same filters and sort on every page. Free keys get one page. See Pagination.

Errors

Every error has the Content-Type application/vnd.api+json and a JSON:API body, whatever Accept header you send. Switch on code, not on the message text.

There are no rate limits.

A request with several bad parameters gets one error for each:

curl -g 'https://feedframer.com/api/v1/me?api_key=YOUR_API_KEY&page[size]=500&sort=newest'

{
  "errors": [
    {
      "status": "422",
      "code": "VALIDATION_ERROR",
      "title": "Invalid Parameter",
      "detail": "The page[size] field must not be greater than 100.",
      "source": { "parameter": "page[size]" }
    },
    {
      "status": "422",
      "code": "VALIDATION_ERROR",
      "title": "Invalid Parameter",
      "detail": "The sort value must be one of: -published_at, published_at, -publishedAt, publishedAt, -id, id.",
      "source": { "parameter": "sort" }
    }
  ]
}

source.parameter names the parameter the way you sent it. These are the validation messages /api/v1/me can return:

The 401 bodies look like this:

{
  "errors": [
    {
      "status": "401",
      "code": "INVALID_API_KEY",
      "title": "Authentication Failed",
      "detail": "The provided API key is invalid."
    }
  ]
}

See Error Handling for handling them in code.

Code examples

• JavaScript
• Next.js
• PHP
• Laravel
• Python
• WordPress
• React
• Vue

You can also try requests in the API Playground when you're logged in.