Get Posts

Retrieve Instagram posts for a creator or profile with engagement metrics and media data. Only Instagram posts are returned.

Query options:

• By creator: Use creator_id to get posts across all of their Instagram profiles. Creators without an Instagram profile return an empty page
• By profile: Use platform + username for a specific profile’s posts. Usernames are matched case-insensitively

Sort options:

• recent: Most recent posts first (default)
• top_engagement: Highest view-based engagement rate first, calculated as (likes + comments) / views. Posts without measurable views sort last
• most_likes: Most likes first
• most_views: Most views first (video content)
• most_comments: Most comments first

Pagination uses an opaque keyset cursor. Pass next_cursor back with the same sort value; cursors cannot be reused across sort orders.

Also callable as the get_posts MCP tool — see the MCP server guide for setup.

Pricing: 0.05 credits per post returned ($0.0005)

GET /v1/posts

cURL

cURL

curl --request GET \
  --url https://api.influship.com/v1/posts \
  --header 'X-API-Key: <api-key>'

200

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "profile_id": "123e4567-e89b-12d3-a456-426614174001",
      "platform": "instagram",
      "platform_id": "CxYz123ABC",
      "url": "https://www.instagram.com/p/CxYz123ABC",
      "posted_at": "2024-01-15T14:30:00Z",
      "type": "image",
      "caption": "Starting the week with a killer workout! 💪",
      "media": {
        "url": "https://cdn.example.com/media/post123.jpg",
        "thumbnail_url": "https://cdn.example.com/thumbnails/post123.jpg",
        "duration_seconds": 45,
        "carousel_items": [
          {
            "index": 0,
            "is_video": false,
            "thumbnail_url": "https://cdn.example.com/thumbnails/carousel_0.jpg"
          }
        ]
      },
      "metrics": {
        "likes": 4500,
        "comments": 120,
        "views": 15000,
        "shares": 50,
        "engagement_rate": 3.8
      },
      "hashtags": [
        "fitness",
        "workout",
        "motivation"
      ],
      "mentions": [
        "nike",
        "gymshark"
      ],
      "location": {
        "name": "Los Angeles, California"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzb3J0IjoicmVjZW50IiwiaWQiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJ2YWx1ZSI6IjIwMjYtMDctMDlUMTI6MDA6MDAuMDAwWiJ9"
}

Authorizations

X-API-Key · string · header · required

Query Parameters

platform · enum<string>

Platform (required with username)

Available options: instagram

Example:

"instagram"

username · string

Username (required with platform)

Required string length: 1 - 50

Example:

"fitness_coach_jane"

creator_id · string<uuid>

Creator ID (use this OR platform+username)

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Example:

"123e4567-e89b-12d3-a456-426614174000"

limit · integer · default: 12

Maximum posts to return

Required range: 1 <= x <= 50

Example:

12

sort · enum<string> · default: recent

Sort order

Available options: recent, top_engagement, most_likes, most_views, most_comments

Example:

"recent"

cursor · string

Opaque keyset cursor from next_cursor. A cursor is bound to the sort order that produced it; using it with another sort returns 400.

Response

200

application/json

Successful response

data · object[] · required

Show child attributes

has_more · boolean · required

Whether more results are available

Example:

true

next_cursor · string | null · required

Opaque keyset cursor for the next page. Reuse it with the same sort value that produced it.

Example:

"eyJzb3J0IjoicmVjZW50IiwiaWQiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJ2YWx1ZSI6IjIwMjYtMDctMDlUMTI6MDA6MDAuMDAwWiJ9"