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 requests
url = "https://api.influship.com/v1/posts"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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": "Invalid value for parameter 'limit': must be between 1 and 100",
"param": "limit",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "unauthorized",
"message": "API key missing or invalid",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "payment_required",
"message": "Payment authentication is required.",
"status_code": 402,
"reason_code": "PAYMENT_ACTION_REQUIRED",
"next_step": "complete_authentication",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "forbidden",
"message": "Your plan does not include access to this endpoint",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "not_found",
"message": "Creator with ID '123e4567-e89b-12d3-a456-426614174000' not found",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded (per minute)",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later.",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "service_unavailable",
"message": "Live Instagram data is temporarily unavailable. Please retry shortly.",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"details": {
"retry_after_seconds": 60,
"upstream_error": "upstream_rate_limited"
}
}
}Posts
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_idto get posts across all of their Instagram profiles. Creators without an Instagram profile return an empty page - By profile: Use
platform+usernamefor 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 lastmost_likes: Most likes firstmost_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 --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 requests
url = "https://api.influship.com/v1/posts"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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": "Invalid value for parameter 'limit': must be between 1 and 100",
"param": "limit",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "unauthorized",
"message": "API key missing or invalid",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "payment_required",
"message": "Payment authentication is required.",
"status_code": 402,
"reason_code": "PAYMENT_ACTION_REQUIRED",
"next_step": "complete_authentication",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "forbidden",
"message": "Your plan does not include access to this endpoint",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "not_found",
"message": "Creator with ID '123e4567-e89b-12d3-a456-426614174000' not found",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded (per minute)",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later.",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "service_unavailable",
"message": "Live Instagram data is temporarily unavailable. Please retry shortly.",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"details": {
"retry_after_seconds": 60,
"upstream_error": "upstream_rate_limited"
}
}
}Query Parameters
Response
Successful response