Influship Posts API

openapi: 3.2.0
info:
  title: Influship Posts 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


    Account-specific credit budgets take precedence over tier defaults. Use the returned

    `RateLimit-Limit-Minute` and `RateLimit-Limit-Hour` headers to read your effective budgets.


    ## Agentic Payments


    Use `https://api.influship.com/openapi.json` to discover endpoints that accept x402 v2 or MPP payments without an API key. It includes `402` payment challenges and `x-payment-info` metadata for the available payment methods.


    ## 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
  x-guidance: 'Use the operation requestBody and query/path parameter schemas exactly as declared. Paid operations return HTTP 402 with x402 v2 and MPP payment challenges when called without payment; retry the same request with either x402 PAYMENT-SIGNATURE credentials (X-PAYMENT is also accepted for compatibility) or MPP Authorization: Payment credentials.'
servers:
- url: https://api.influship.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Posts
  description: Retrieve and analyze social media posts with engagement metrics, media content, and performance data.
paths:
  /v1/posts:
    get:
      operationId: getPosts
      summary: Get Posts
      tags:
      - Posts
      description: '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)'
      parameters:
      - schema:
          description: Platform (required with username)
          $ref: '#/components/schemas/Platform'
        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:
          default: recent
          description: Sort order
          $ref: '#/components/schemas/PostSort'
        in: query
        name: sort
        description: Sort order
      - schema:
          description: Opaque keyset cursor from next_cursor. A cursor is bound to the sort order that produced it; using it with another sort returns 400.
          type: string
        in: query
        name: cursor
        description: Opaque keyset cursor from next_cursor. A cursor is bound to the sort order that produced it; using it with another sort returns 400.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsResponse'
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '402':
          description: Payment required. API-key and OAuth requests receive the canonical classified billing envelope. No-key requests receive x402 and MPP challenges in response headers.
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '429':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '503':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
      security:
      - apiKey: []
      x-payment-info:
        offers:
        - method: tempo
          intent: charge
          amount: null
          currency: '0x20c000000000000000000000b9537d11c60e8b50'
          recipient: '0x6d02E3f7C68E7492Cc5474Ef8ce17DedFD11df89'
          network: eip155:4217
components:
  schemas:
    Platform:
      type: string
      enum:
      - instagram
      description: Social media platform
      example: instagram
    PostType:
      type: string
      enum:
      - image
      - video
      - carousel
      - reel
      - story
      description: Type of post
      example: image
    Error401:
      description: Authentication error response
      examples:
      - error:
          code: unauthorized
          message: API key missing or invalid
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    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:
          description: Post caption
          example: Starting the week with a killer workout! 💪
          type:
          - string
          - 'null'
        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
        coauthor_usernames:
          description: Observed Instagram coauthor usernames. profile_id identifies the owning profile.
          example:
          - gopro
          type: array
          items:
            type: string
        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
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              description: Machine-readable error code
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable error message
              example: Request validation failed
            status_code:
              description: HTTP status code repeated for clients that consume the error body
              example: 402
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            param:
              description: Parameter that caused the error (if applicable)
              example: query
              type: string
            request_id:
              description: Optional request ID for debugging. Read the X-Request-Id response header when absent.
              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
    Error503:
      description: 'Service temporarily unavailable: a live data upstream, or a creator search, match or lookalike request that could not finish in time. Check Retry-After when present and retry with bounded backoff.'
      examples:
      - 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
      $ref: '#/components/schemas/Error'
    PostsResponseData:
      type: array
      items:
        $ref: '#/components/schemas/PostResponseData'
    PostLocation:
      type: object
      properties:
        name:
          description: Location name
          example: Los Angeles, California
          type:
          - string
          - 'null'
      required:
      - name
      additionalProperties: false
      description: Post location information
    Error403:
      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
      $ref: '#/components/schemas/Error'
    Error429:
      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
      $ref: '#/components/schemas/Error'
    Error400:
      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
      $ref: '#/components/schemas/Error'
    Error500:
      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
      $ref: '#/components/schemas/Error'
    PostSort:
      type: string
      enum:
      - recent
      - top_engagement
      - most_likes
      - most_views
      - most_comments
      description: Stable post ordering. top_engagement uses (likes + comments) / views, with posts that have no measurable views sorted last.
      example: recent
    ErrorCode:
      type: string
      enum:
      - validation_error
      - invalid_parameter
      - missing_parameter
      - unauthorized
      - forbidden
      - payment_required
      - insufficient_credits
      - not_found
      - rate_limit_exceeded
      - quota_exceeded
      - internal_error
      - service_unavailable
      - upstream_contract_broken
      - database_error
      - seed_not_found
      - invalid_seeds
      - seed_resolution_failed
      - lookalike_failed
      - get_profiles_failed
      - post_analysis_failed
      - match_failed
      - scraping_failed
      - transcript_unavailable
      - transcript_not_available
      - transcription_limit_exceeded
      - transcription_unavailable
      description: Machine-readable error code for programmatic handling
      example: validation_error
    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:
          description: Thumbnail URL for this item. Cover frame for videos. A durable hosted image URL when one is available; otherwise the platform thumbnail URL, which expires.
          example: https://cdn.example.com/thumbnails/carousel_0.jpg
          type:
          - string
          - 'null'
      required:
      - index
      - is_video
      - thumbnail_url
      additionalProperties: false
    PostMedia:
      type: object
      properties:
        url:
          description: Cover/primary image URL for image and carousel posts. A durable hosted image URL when one is available; otherwise the platform image URL, which expires, so download it promptly. Null for video posts — call GET /v1/raw/instagram/post/{shortcode} for a fresh, downloadable video URL.
          example: https://cdn.example.com/media/post123.jpg
          type:
          - string
          - 'null'
        thumbnail_url:
          description: Thumbnail URL. For videos, this is the cover frame. A durable hosted image URL when one is available; otherwise the platform thumbnail URL, which expires. If a video has no hosted cover and its platform cover has expired, this is a hosted frame from the video.
          example: https://cdn.example.com/thumbnails/post123.jpg
          type:
          - string
          - 'null'
        duration_seconds:
          description: Video duration in seconds. Null for non-video posts.
          example: 45
          type:
          - number
          - 'null'
        carousel_items:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/PostMediaCarouselItem'
          - type: 'null'
          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
    PostsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PostsResponseData'
        has_more:
          type: boolean
          description: Whether more results are available
          example: true
        next_cursor:
          description: Opaque keyset cursor for the next page. Reuse it with the same sort value that produced it.
          example: eyJzb3J0IjoicmVjZW50IiwiaWQiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJ2YWx1ZSI6IjIwMjYtMDctMDlUMTI6MDA6MDAuMDAwWiJ9
          type:
          - string
          - 'null'
      required:
      - data
      - has_more
      - next_cursor
      additionalProperties: false
    PostMetrics:
      type: object
      properties:
        likes:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: Like count
          example: 4500
        comments:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: Comment count
          example: 120
        views:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: View count (for video content)
          example: 15000
        shares:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: Share count
          example: 50
        engagement_rate:
          description: Engagement rate for this post as a percentage (e.g. 3.8 means 3.8%)
          example: 3.8
          type:
          - number
          - 'null'
      required:
      - likes
      - comments
      - views
      - shares
      - engagement_rate
      additionalProperties: false
      description: Post engagement metrics
    Error404:
      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
      $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key