Influship Profiles API

openapi: 3.2.0
info:
  title: Influship Profiles 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: Profiles
  description: Access individual social media profiles with detailed metrics, growth data, and activity information. Profiles are platform-specific accounts linked to creators.
paths:
  /v1/profiles/{platform}/{username}:
    get:
      operationId: getProfileByPlatformUsername
      summary: Get Profile by Platform and Username
      tags:
      - Profiles
      description: 'Retrieve an Instagram profile''s identity, metrics, growth statistics, and activity information.


        **Response includes:**

        - Basic info (bio, avatar, verification status)

        - Performance metrics (followers, engagement rate, avg likes/comments)

        - Growth data (30-day follower growth, monthly rate)

        - Activity data (last post date, posting frequency)


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


        **Pricing**: 0.1 credits per request ($0.001)'
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Platform name
          example: instagram
        in: path
        name: platform
        required: true
        description: Platform name
      - schema:
          type: string
          minLength: 1
          maxLength: 50
          description: Username on the platform
          example: fitness_coach_jane
        in: path
        name: username
        required: true
        description: Username on the platform
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        '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
  /v1/profiles/lookup:
    post:
      operationId: lookupProfiles
      summary: Batch Lookup Profiles
      tags:
      - Profiles
      description: 'Look up multiple profiles in a single request. Efficiently retrieve data for up to 100 profiles at once.


        **Response includes:**

        - `data`: Array of resolved profiles

        - `not_found`: Array of profiles that weren''t found. Use on-demand ingestion to add a public Instagram handle


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


        **Pricing**: 0.1 credits per profile ($0.001)'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfilesLookupRequest'
        description: Batch lookup profiles request
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilesLookupResponse'
        '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'
        '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:
    ProfileResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ProfileResponseData'
        warning:
          description: Present when partial results were returned because profile metrics/data were skipped due to integrity issues.
          type: string
      required:
      - data
      additionalProperties: false
    Platform:
      type: string
      enum:
      - instagram
      description: Social media platform
      example: instagram
    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'
    ProfileNotFoundItem:
      type: object
      properties:
        platform:
          $ref: '#/components/schemas/Platform'
        username:
          type: string
          example: unknown_user
      required:
      - platform
      - username
      additionalProperties: false
    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
    ProfilesLookupResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProfileResponseData'
          description: Profiles that were found
        not_found:
          type: array
          items:
            $ref: '#/components/schemas/ProfileNotFoundItem'
          description: Profiles that were not found
      required:
      - data
      - not_found
      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'
    ProfileActivity:
      type: object
      properties:
        last_post_at:
          anyOf:
          - 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)))$
          - type: 'null'
          description: Timestamp of last post
          example: '2024-01-15T14:30:00Z'
      required:
      - last_post_at
      additionalProperties: false
      description: Profile activity 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'
    ProfileGrowth:
      type: object
      properties:
        followers_30d_pct:
          type: number
          description: Follower growth percentage over 30 days (e.g. 2.5 means +2.5%)
          example: 2.5
      required:
      - followers_30d_pct
      additionalProperties: false
      description: Profile growth statistics
    ProfileMetrics:
      type: object
      properties:
        followers:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Follower count
          example: 125000
        following:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Following count
          example: 1200
        posts:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Total post count
          example: 450
        posts_last_30d:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Posts in the last 30 days
          example: 12
        engagement_rate:
          anyOf:
          - type: number
            minimum: 0
          - type: 'null'
          description: Engagement rate as a percentage, null if unknown (e.g. 3.5 means 3.5%)
          example: 3.5
        avg_likes_recent:
          type: number
          minimum: 0
          description: Average likes on recent posts
          example: 4500
        avg_comments_recent:
          type: number
          minimum: 0
          description: Average comments on recent posts
          example: 120
        avg_views_recent:
          anyOf:
          - type: number
            minimum: 0
          - type: 'null'
          description: Average views on recent posts (for video content)
          example: 15000
        posts_per_week:
          type: number
          minimum: 0
          description: Average posts per week
          example: 2.5
      required:
      - followers
      - following
      - posts
      - posts_last_30d
      - engagement_rate
      - avg_likes_recent
      - avg_comments_recent
      - avg_views_recent
      - posts_per_week
      additionalProperties: false
      description: Profile performance metrics
    ProfilesLookupRequest:
      type: object
      properties:
        profiles:
          minItems: 1
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/ProfileLookupItem'
          description: Profiles to lookup
      required:
      - profiles
      description: Batch lookup profiles request
      examples:
      - profiles:
        - platform: instagram
          username: fitness_coach_jane
        - platform: instagram
          username: wellness_guru
        - platform: instagram
          username: healthy_eating_tips
    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'
    ProfileLookupItem:
      type: object
      properties:
        platform:
          $ref: '#/components/schemas/Platform'
        username:
          type: string
          minLength: 1
          maxLength: 50
          description: Username to lookup
          example: fitness_coach_jane
      required:
      - platform
      - username
    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
    ProfileResponseData:
      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: Profile unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        creator_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: Creator unique identifier
          example: 123e4567-e89b-12d3-a456-426614174001
        platform:
          $ref: '#/components/schemas/Platform'
        username:
          type: string
          description: Profile username
          example: fitness_coach_jane
        display_name:
          description: Display name
          example: Jane Fitness
          type:
          - string
          - 'null'
        bio:
          description: Profile bio
          example: Fitness coach & wellness advocate
          type:
          - string
          - 'null'
        avatar_url:
          description: Avatar URL
          example: https://cdn.example.com/avatars/jane.jpg
          type:
          - string
          - 'null'
        url:
          type: string
          format: uri
          description: Profile URL
          example: https://www.instagram.com/fitness_coach_jane
        external_url:
          description: External website URL from bio
          example: https://janefitness.com
          type:
          - string
          - 'null'
        is_verified:
          type: boolean
          description: Whether the account is verified
          example: true
        is_business:
          type: boolean
          description: Whether this is a business account
          example: true
        is_private:
          type: boolean
          description: Whether the account is private
          example: false
        category:
          description: Account category
          example: Health/Beauty
          type:
          - string
          - 'null'
        pronouns:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Listed pronouns
          example:
          - she
          - her
        metrics:
          $ref: '#/components/schemas/ProfileMetrics'
        growth:
          $ref: '#/components/schemas/ProfileGrowth'
        activity:
          $ref: '#/components/schemas/ProfileActivity'
        data_updated_at:
          anyOf:
          - 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)))$
          - type: 'null'
          description: Last data refresh timestamp
          example: '2024-01-15T14:30:00Z'
      required:
      - id
      - creator_id
      - platform
      - username
      - display_name
      - bio
      - avatar_url
      - url
      - external_url
      - is_verified
      - is_business
      - is_private
      - category
      - pronouns
      - metrics
      - growth
      - activity
      - data_updated_at
      additionalProperties: false
      description: Full profile details
    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