> ## Documentation Index > Fetch the complete documentation index at: https://docs.influship.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 engagement rate first - `most_likes`: Most likes first - `most_views`: Most views first (video content) - `most_comments`: Most comments first Also callable as the `get_posts` MCP tool — see [the MCP server guide](/guides/mcp-server) for setup. **Pricing**: 0.05 credits per post returned ($0.0005) ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/influship-api/openapi.documented.yml get /v1/posts openapi: 3.1.0 info: title: Influship API version: 1.0.0 description: > Public API for creator search, profile lookup, and campaign-fit analysis. ## Authentication Send your API key in the `X-API-Key` header on every authenticated request. ```bash curl -H "X-API-Key: your_api_key" https://api.influship.com/v1/creators/autocomplete?q=fitness ``` ## Billing and Rate Limits The API uses credit-based billing and credit-based rate limits. - every endpoint has a credit cost - successful responses include `X-Credits-Charged` and `X-Credits-Features` - rate limits are enforced with per-minute and per-hour credit budgets - rate limit state is returned in the `RateLimit-*` headers ## Pagination List endpoints use cursor pagination. - send `limit` to control page size - use `next_cursor` from the response to fetch the next page - stop when `has_more` is `false` Search has one special rule: - `POST /v1/search` creates a persisted search session - `GET /v1/search/{id}` paginates that session for free - free pagination is capped by the original search `limit` ## Errors Errors use a consistent shape: ```json { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded (per minute)" } } ``` See each operation for exact request and response schemas. contact: name: Influship Support email: support@influship.com license: name: Proprietary url: https://influship.com/terms servers: - url: https://api.influship.com description: Production security: - ApiKeyAuth: [] tags: - name: Health description: API health and status endpoints - name: Creators description: >- Retrieve creator profiles and discover new creators through search, autocomplete, and lookalike matching. Creators are cross-platform entities that may have profiles on multiple social networks. - name: Profiles description: >- Access individual social media profiles with detailed metrics, growth data, and activity information. Profiles are platform-specific accounts linked to creators. - name: Creator Emails description: >- Look up known creator email addresses by creator ID or social username. Empty or unresolved results are not billable. - name: Posts description: >- Retrieve and analyze social media posts with engagement metrics, media content, and performance data. - name: Search description: >- AI-powered semantic search to find creators using natural language queries. Understands intent and context to match creators based on content themes, audience, and style. - name: Live Scraping description: >- Fetch fresh data directly from social platforms in real-time. Use when you need the most current information or data for profiles not yet in our database. paths: /v1/posts: get: tags: - Posts summary: Get Posts description: >- 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 engagement rate first - `most_likes`: Most likes first - `most_views`: Most views first (video content) - `most_comments`: Most comments first Also callable as the `get_posts` MCP tool — see [the MCP server guide](/guides/mcp-server) for setup. **Pricing**: 0.05 credits per post returned ($0.0005) operationId: getPosts parameters: - schema: $ref: '#/components/schemas/Platform' description: Platform (required with username) in: query name: platform description: Platform (required with username) - schema: description: Username (required with platform) example: fitness_coach_jane type: string minLength: 1 maxLength: 50 in: query name: username description: Username (required with platform) - schema: description: Creator ID (use this OR platform+username) example: 123e4567-e89b-12d3-a456-426614174000 type: string format: uuid 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)$ in: query name: creator_id description: Creator ID (use this OR platform+username) - schema: default: 12 description: Maximum posts to return example: 12 type: integer minimum: 1 maximum: 50 in: query name: limit description: Maximum posts to return - schema: $ref: '#/components/schemas/PostSort' default: recent description: Sort order in: query name: sort description: Sort order - schema: description: Pagination cursor for next page type: string in: query name: cursor description: Pagination cursor for next page responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PostsResponse' '400': description: Validation error response content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Authentication error response content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Permission error response content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Not found error response content: application/json: schema: $ref: '#/components/schemas/Error404' '429': description: >- Rate limit exceeded response. Check Retry-After header for backoff timing. Also returned (without RateLimit-* headers) when an IP is temporarily blocked after repeated failed authentication attempts. content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: Internal server error response content: application/json: schema: $ref: '#/components/schemas/Error500' x-codeSamples: - lang: JavaScript source: |- 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); } - lang: Python source: |- 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) components: schemas: Platform: type: string enum: - instagram description: Social media platform example: instagram PostSort: type: string enum: - recent - top_engagement - most_likes - most_views - most_comments description: Sort order for posts example: recent PostsResponse: type: object properties: data: $ref: '#/components/schemas/PostsResponseData' has_more: type: boolean description: Whether more results are available example: true next_cursor: type: - string - 'null' description: Cursor for the next page of results example: eyJvZmZzZXQiOjI1fQ== required: - data - has_more - next_cursor additionalProperties: false Error400: $ref: '#/components/schemas/Error' description: Validation error response examples: - 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 Error401: $ref: '#/components/schemas/Error' description: Authentication error response examples: - error: code: unauthorized message: API key missing or invalid request_id: 550e8400-e29b-41d4-a716-446655440000 Error403: $ref: '#/components/schemas/Error' description: Permission error response examples: - error: code: forbidden message: Your plan does not include access to this endpoint request_id: 550e8400-e29b-41d4-a716-446655440000 Error404: $ref: '#/components/schemas/Error' description: Not found error response examples: - error: code: not_found message: Creator with ID '123e4567-e89b-12d3-a456-426614174000' not found request_id: 550e8400-e29b-41d4-a716-446655440000 Error429: $ref: '#/components/schemas/Error' description: >- Rate limit exceeded response. Check Retry-After header for backoff timing. Also returned (without RateLimit-* headers) when an IP is temporarily blocked after repeated failed authentication attempts. examples: - error: code: rate_limit_exceeded message: Rate limit exceeded (per minute) request_id: 550e8400-e29b-41d4-a716-446655440000 - error: code: rate_limit_exceeded message: Rate limit exceeded (per hour) request_id: 550e8400-e29b-41d4-a716-446655440001 - error: code: rate_limit_exceeded message: Too many failed authentication attempts. Please try again later. request_id: 550e8400-e29b-41d4-a716-446655440002 Error500: $ref: '#/components/schemas/Error' description: Internal server error response examples: - error: code: internal_error message: An unexpected error occurred. Please try again later. request_id: 550e8400-e29b-41d4-a716-446655440000 PostsResponseData: type: array items: $ref: '#/components/schemas/PostResponseData' Error: type: object properties: error: type: object properties: code: $ref: '#/components/schemas/ErrorCode' description: Machine-readable error code message: type: string description: Human-readable error message example: Request validation failed param: description: Parameter that caused the error (if applicable) example: query type: string request_id: description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 type: string details: description: Structured error context (e.g., field-level validation issues) type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false required: - error additionalProperties: false PostResponseData: type: object properties: id: type: string format: uuid 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)$ description: Post unique identifier example: 123e4567-e89b-12d3-a456-426614174000 profile_id: type: string format: uuid 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)$ description: Profile unique identifier example: 123e4567-e89b-12d3-a456-426614174001 platform: $ref: '#/components/schemas/Platform' platform_id: type: string description: Platform-specific post ID example: CxYz123ABC url: type: string format: uri description: Post URL example: https://www.instagram.com/p/CxYz123ABC posted_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: Post timestamp example: '2024-01-15T14:30:00Z' type: $ref: '#/components/schemas/PostType' caption: type: - string - 'null' description: Post caption example: Starting the week with a killer workout! 💪 media: $ref: '#/components/schemas/PostMedia' metrics: $ref: '#/components/schemas/PostMetrics' hashtags: type: array items: type: string description: Hashtags used in the post example: - fitness - workout - motivation mentions: type: array items: type: string description: Usernames mentioned in the post example: - nike - gymshark location: anyOf: - $ref: '#/components/schemas/PostLocation' - type: 'null' description: Post location (if tagged) required: - id - profile_id - platform - platform_id - url - posted_at - type - caption - media - metrics - hashtags - mentions - location additionalProperties: false description: Full post details ErrorCode: type: string enum: - validation_error - invalid_parameter - missing_parameter - unauthorized - forbidden - payment_required - not_found - rate_limit_exceeded - internal_error - service_unavailable - database_error - seed_not_found - invalid_seeds - seed_resolution_failed - lookalike_failed - get_profiles_failed - post_analysis_failed - match_failed - scraping_failed - transcript_unavailable description: Machine-readable error code for programmatic handling example: validation_error PostType: type: string enum: - image - video - carousel - reel - story description: Type of post example: image PostMedia: type: object properties: url: type: - string - 'null' description: >- Cover/primary image URL for image and carousel posts. Null for video posts — call GET /v1/raw/instagram/post/{shortcode} for a fresh, downloadable video URL. Note: returned image URLs are Instagram CDN URLs and may expire; a future change will migrate to persistent R2-hosted URLs. example: https://cdn.example.com/media/post123.jpg thumbnail_url: type: - string - 'null' description: Thumbnail URL. For videos, this is the cover frame. example: https://cdn.example.com/thumbnails/post123.jpg duration_seconds: type: - number - 'null' description: Video duration in seconds. Null for non-video posts. example: 45 carousel_items: type: - array - 'null' items: $ref: '#/components/schemas/PostMediaCarouselItem' description: >- Per-item structure for carousel posts. Null for non-carousel posts. Per-item video_url is intentionally omitted (would be stale). For fresh video URLs, call GET /v1/raw/instagram/post/{shortcode}. required: - url - thumbnail_url - duration_seconds - carousel_items additionalProperties: false description: Post media information PostMetrics: type: object properties: likes: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 description: Like count example: 4500 comments: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 description: Comment count example: 120 views: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 description: View count (for video content) example: 15000 shares: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 description: Share count example: 50 engagement_rate: type: - number - 'null' description: Engagement rate for this post as a percentage (e.g. 3.8 means 3.8%) example: 3.8 required: - likes - comments - views - shares - engagement_rate additionalProperties: false description: Post engagement metrics PostLocation: type: object properties: name: type: - string - 'null' description: Location name example: Los Angeles, California required: - name additionalProperties: false description: Post location information PostMediaCarouselItem: type: object properties: index: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based position in the carousel. example: 0 is_video: type: boolean description: True if this item is a video. example: false thumbnail_url: type: - string - 'null' description: Thumbnail URL for this item. Cover frame for videos. example: https://cdn.example.com/thumbnails/carousel_0.jpg required: - index - is_video - thumbnail_url additionalProperties: false securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````