Get Search Results Page

cURL

curl --request GET \
  --url https://api.influship.com/v1/search/{id} \
  --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 searchRetrieveResponse of client.search.retrieve(
  '123e4567-e89b-12d3-a456-426614174000',
)) {
  console.log(searchRetrieveResponse.creator);
}

{
  "data": [
    {
      "creator": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Jane Fitness",
        "bio": "Fitness coach and home-workout creator",
        "avatar_url": null
      },
      "relevant_profile": null,
      "primary_profile": null,
      "location_unverified": null,
      "match": {
        "score": 0.85,
        "confidence": 0.85,
        "low_confidence": false,
        "ranking_source": "reranked",
        "reasons": [
          "Publishes practical home-workout tutorials."
        ],
        "evidence": [
          {
            "text": "Publishes practical home-workout tutorials.",
            "provenance": "post_evidence",
            "fact_id": null,
            "source_post_id": "23256c2e-51fa-4389-a4a1-945e461e951b",
            "evidence_quote": "Here are three bodyweight exercises for a quick home workout."
          }
        ]
      }
    }
  ],
  "quality": {
    "mode": "reranked",
    "reason": null
  },
  "search_id": "987fcdeb-51a2-43d7-8b90-123456789abc",
  "total": 1,
  "has_more": false,
  "next_cursor": null
}

{
  "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"
    }
  }
}

GET

{id}

cURL

curl --request GET \
  --url https://api.influship.com/v1/search/{id} \
  --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 searchRetrieveResponse of client.search.retrieve(
  '123e4567-e89b-12d3-a456-426614174000',
)) {
  console.log(searchRetrieveResponse.creator);
}

{
  "data": [
    {
      "creator": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Jane Fitness",
        "bio": "Fitness coach and home-workout creator",
        "avatar_url": null
      },
      "relevant_profile": null,
      "primary_profile": null,
      "location_unverified": null,
      "match": {
        "score": 0.85,
        "confidence": 0.85,
        "low_confidence": false,
        "ranking_source": "reranked",
        "reasons": [
          "Publishes practical home-workout tutorials."
        ],
        "evidence": [
          {
            "text": "Publishes practical home-workout tutorials.",
            "provenance": "post_evidence",
            "fact_id": null,
            "source_post_id": "23256c2e-51fa-4389-a4a1-945e461e951b",
            "evidence_quote": "Here are three bodyweight exercises for a quick home workout."
          }
        ]
      }
    }
  ],
  "quality": {
    "mode": "reranked",
    "reason": null
  },
  "search_id": "987fcdeb-51a2-43d7-8b90-123456789abc",
  "total": 1,
  "has_more": false,
  "next_cursor": null
}

{
  "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"
    }
  }
}

Authorizations

X-API-Key

string

header

required

Path Parameters

string<uuid>

required

Search ID returned from POST /v1/search

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)$

Example:

"123e4567-e89b-12d3-a456-426614174000"

Query Parameters

limit

integer

default:25

Maximum results to return

Required range: 1 <= x <= 100

Example:

25

cursor

string

Pagination cursor for next page

Response

Successful response

data

object[]

required

Show child attributes

search_id

string<uuid>

required

Search ID. Use with GET /v1/search/{id} for free pagination.

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)$

Example:

"123e4567-e89b-12d3-a456-426614174000"

total

integer

required

Total number of results across all pages

Required range: -9007199254740991 <= x <= 9007199254740991

Example:

1

has_more

boolean

required

Whether more results are available

Example:

false

next_cursor

string | null

required

Cursor for the next page

Example:

null

quality

object

How results were ranked: all with AI relevance scoring, a mix of AI and discovery ranking, or discovery ranking throughout. When omitted, treat the response as reranked. Use each match.ranking_source to interpret its score.

Option 1
Option 2
Option 3

Show child attributes

Overview

Endpoints

Authorizations

Path Parameters

Query Parameters

Response