Get Posts

Retrieve posts for a creator or profile with engagement metrics and media data.

Query options:

• By creator: Use creator_id to get posts across all their profiles
• By profile: Use platform + username for a specific profile’s posts

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>'

import Influship from 'influship';

const client = new Influship({
  apiKey: process.env['INFLUSHIP_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const postListResponse of client.posts.list()) {
  console.log(postListResponse.id);
}

import os
from influship import Influship

client = Influship(
    api_key=os.environ.get("INFLUSHIP_API_KEY"),  # This is the default and can be omitted
)
page = client.posts.list()
page = page.data[0]
print(page.id)

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"
}

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "param": "query",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {}
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "param": "query",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {}
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "param": "query",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {}
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "param": "query",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {}
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "param": "query",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {}
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "param": "query",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {}
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "param": "query",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {}
  }
}

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"