> ## 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 Search Results Page

> Paginate through results from a previous search. Use the `search_id` returned by `POST /v1/search` to fetch additional pages.

Search sessions expire after 1 hour. After expiry, a new search must be run.

**Pricing**: 0 credits (included with initial search)



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/influship-api/openapi.documented.yml get /v1/search/{id}
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


    ## Agentic Payments


    The security entries in this base SDK contract describe `X-API-Key`
    authentication. The hosted discovery document at
    `https://api.influship.com/openapi.json` augments currently enabled paid
    operations with `402` responses and `x-payment-info` metadata for x402 v2
    and MPP. Use that hosted document when building no-key payment clients
    because supported operations and payment rails are deployment-dependent.


    ## 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/search/{id}:
    get:
      tags:
        - Search
      summary: Get Search Results Page
      description: >-
        Paginate through results from a previous search. Use the `search_id`
        returned by `POST /v1/search` to fetch additional pages.


        Search sessions expire after 1 hour. After expiry, a new search must be
        run.


        **Pricing**: 0 credits (included with initial search)
      operationId: getSearchResults
      parameters:
        - schema:
            default: 25
            description: Maximum results to return
            example: 25
            type: integer
            minimum: 1
            maximum: 100
          in: query
          name: limit
          description: Maximum results to return
        - schema:
            description: Pagination cursor for next page
            type: string
          in: query
          name: cursor
          description: Pagination cursor for next page
        - schema:
            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: Search ID returned from POST /v1/search
            example: 123e4567-e89b-12d3-a456-426614174000
          in: path
          name: id
          required: true
          description: Search ID returned from POST /v1/search
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '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 searchRetrieveResponse of client.search.retrieve(
              '123e4567-e89b-12d3-a456-426614174000',
            )) {
              console.log(searchRetrieveResponse.creator);
            }
        - 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.search.retrieve(
                id="123e4567-e89b-12d3-a456-426614174000",
            )
            page = page.data[0]
            print(page.creator)
components:
  schemas:
    SearchResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SearchResponseData'
        search_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: Search ID. Use with GET /v1/search/{id} for free pagination.
          example: 123e4567-e89b-12d3-a456-426614174000
        total:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Total number of results across all pages
          example: 87
        has_more:
          type: boolean
          description: Whether more results are available
          example: true
        next_cursor:
          type:
            - string
            - 'null'
          description: Cursor for the next page
          example: eyJvZmZzZXQiOjI1fQ==
      required:
        - data
        - search_id
        - total
        - 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
    SearchResponseData:
      type: array
      items:
        $ref: '#/components/schemas/SearchResultItem'
    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
    SearchResultItem:
      type: object
      properties:
        creator:
          $ref: '#/components/schemas/CreatorBasic'
        relevant_profile:
          anyOf:
            - $ref: '#/components/schemas/ProfileSummary'
            - type: 'null'
          description: >-
            Most relevant profile based on search query (null if no profile data
            available)
        primary_profile:
          anyOf:
            - $ref: '#/components/schemas/ProfileSummary'
            - type: 'null'
          description: >-
            Primary profile (largest audience, null if no profile data
            available)
        match:
          $ref: '#/components/schemas/MatchInfo'
        location_unverified:
          type:
            - boolean
            - 'null'
          description: >-
            True when the query required a country but this creator location is
            unverified; false when the known location satisfies it; null when
            the query set no geography requirement. Known mismatches are
            excluded from results.
          example: true
      required:
        - creator
        - relevant_profile
        - primary_profile
        - match
        - location_unverified
      additionalProperties: false
    ErrorCode:
      type: string
      enum:
        - validation_error
        - invalid_parameter
        - missing_parameter
        - unauthorized
        - forbidden
        - payment_required
        - not_found
        - rate_limit_exceeded
        - quota_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
    CreatorBasic:
      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: Creator unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Creator display name
          example: Jane Fitness
        bio:
          type:
            - string
            - 'null'
          description: Creator bio
          example: Fitness coach & wellness advocate
        avatar_url:
          type:
            - string
            - 'null'
          description: Avatar URL
          example: https://cdn.example.com/avatars/jane.jpg
      required:
        - id
        - name
        - bio
        - avatar_url
      additionalProperties: false
      description: Basic creator information
    ProfileSummary:
      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
        platform:
          $ref: '#/components/schemas/Platform'
        username:
          type: string
          description: Profile username
          example: fitness_coach_jane
        url:
          type: string
          format: uri
          description: Profile URL
          example: https://www.instagram.com/fitness_coach_jane
        followers:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 9007199254740991
          description: Follower count (null if unknown)
          example: 125000
        engagement_rate:
          type:
            - number
            - 'null'
          minimum: 0
          description: >-
            Engagement rate as a percentage, null if unknown (e.g. 3.5 means
            3.5%)
          example: 3.5
        is_verified:
          type: boolean
          description: Whether the account is verified
          example: true
      required:
        - id
        - platform
        - username
        - url
        - followers
        - engagement_rate
        - is_verified
      additionalProperties: false
      description: Abbreviated profile information
    MatchInfo:
      type: object
      properties:
        score:
          type: number
          minimum: 0
          maximum: 1
          description: Match relevance score (0-1)
          example: 0.85
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Rerank relevance as a 0-1 confidence. Mirrors `score`.
          example: 0.85
        low_confidence:
          type: boolean
          description: >-
            True when `confidence` is at/below the low-confidence threshold. A
            non-breaking marker for the weak tail so you can separate "weaker
            matches" instead of treating every result as a strong match.
          example: false
        reasons:
          type: array
          items:
            type: string
          description: Human-readable match reasons (plain text).
          example:
            - Active fitness content creator
            - High engagement on workout posts
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/MatchReasonEvidence'
          description: >-
            Evidence-grounded version of `reasons`, in the same order: each
            reason has a provenance label and, where it rests on a post, the
            backing `source_post_id` and a verbatim `evidence_quote`.
      required:
        - score
        - confidence
        - low_confidence
        - reasons
        - evidence
      additionalProperties: false
      description: Search match information
    Platform:
      type: string
      enum:
        - instagram
      description: Social media platform
      example: instagram
    MatchReasonEvidence:
      type: object
      properties:
        text:
          type: string
          description: Human-readable reason this creator matched.
          example: Publishes ingredient-education Reels on sensitive-skin routines.
        provenance:
          $ref: '#/components/schemas/ReasonProvenance'
        fact_id:
          type:
            - string
            - 'null'
          description: Stored profile fact backing this reason, or null.
        source_post_id:
          type:
            - string
            - 'null'
          description: >-
            Post that evidences this reason (use with GET /v1/posts/{id}), or
            null for non-post-backed reasons.
        evidence_quote:
          type:
            - string
            - 'null'
          description: >-
            Verbatim sentence copied from the source post caption/transcript
            that best supports this reason. Present only for `post_evidence`
            reasons where a genuinely supporting sentence exists — omitted
            (null) rather than filled with unrelated post text. Never
            model-generated.
          example: Today we break down why fragrance wrecks a sensitive-skin barrier…
      required:
        - text
        - provenance
        - fact_id
        - source_post_id
        - evidence_quote
      additionalProperties: false
      description: A single evidence-grounded match reason.
    ReasonProvenance:
      type: string
      enum:
        - post_evidence
        - profile_fact
        - inferred
      description: >-
        How grounded a match reason is, strongest first. `post_evidence`: backed
        by a specific post you can open (see `source_post_id` /
        `evidence_quote`). `profile_fact`: backed by a stored profile fact
        without a clickable source post — weaker than post-backed. `inferred`:
        model reasoning over the profile with no direct post evidence.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````