> ## 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. # AI-Powered Creator Search > Search for creators using natural language queries. The AI understands intent and context to match creators based on content themes, audience demographics, and style. The response includes a `search_id` that can be used with `GET /v1/search/{id}` to paginate through results for free. **Use cases:** - Find creators in a specific niche ("vegan food bloggers in LA") - Discover creators with specific audience characteristics ("fitness influencers with millennial audience") - Search by content style ("creators who post cinematic travel videos") Also callable as the `search_creators` MCP tool — see [the MCP server guide](/guides/mcp-server) for setup. **Pricing**: 25 credits base + 2 credits per creator returned ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/influship-api/openapi.documented.yml post /v1/search 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/search: post: tags: - Search summary: AI-Powered Creator Search description: >- Search for creators using natural language queries. The AI understands intent and context to match creators based on content themes, audience demographics, and style. The response includes a `search_id` that can be used with `GET /v1/search/{id}` to paginate through results for free. **Use cases:** - Find creators in a specific niche ("vegan food bloggers in LA") - Discover creators with specific audience characteristics ("fitness influencers with millennial audience") - Search by content style ("creators who post cinematic travel videos") Also callable as the `search_creators` MCP tool — see [the MCP server guide](/guides/mcp-server) for setup. **Pricing**: 25 credits base + 2 credits per creator returned operationId: searchCreators requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' description: AI-powered semantic search request 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' '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' '503': description: >- Service unavailable response. Live data endpoints may return this for temporary upstream platform throttling; check Retry-After before retrying. content: application/json: schema: $ref: '#/components/schemas/Error503' 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 }); const search = await client.search.create({ query: 'fitness influencers who post workout videos' }); console.log(search.search_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 ) search = client.search.create( query="fitness influencers who post workout videos", ) print(search.search_id) components: schemas: SearchRequest: type: object properties: query: type: string minLength: 1 maxLength: 500 description: Natural language search query example: fitness influencers with 100k+ followers who post workout videos platforms: description: Filter results to specific platforms example: - instagram type: array items: $ref: '#/components/schemas/Platform' filters: $ref: '#/components/schemas/CommonFilters' description: Additional filters limit: default: 25 description: Maximum results to return example: 25 type: integer minimum: 1 maximum: 100 creator_kinds: description: >- Restrict results to specific creator kinds (e.g. INFLUENCER vs THEME_PAGE). Omit for no filter. example: - INFLUENCER minItems: 1 type: array items: type: string enum: - INFLUENCER - THEME_PAGE required: - query description: AI-powered semantic search request examples: - query: fitness influencers who post workout videos limit: 10 - query: sustainable fashion creators platforms: - instagram filters: followers: min: 50000 max: 500000 engagement_rate: min: 2 verified: true limit: 25 creator_kinds: - INFLUENCER 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 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 Error503: $ref: '#/components/schemas/Error' description: >- Service unavailable response. Live data endpoints may return this for temporary upstream platform throttling; check Retry-After before retrying. 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 Platform: type: string enum: - instagram description: Social media platform example: instagram CommonFilters: type: object properties: followers: $ref: '#/components/schemas/FollowersFilter' description: Filter by follower count engagement_rate: $ref: '#/components/schemas/EngagementRateFilter' description: Filter by engagement rate verified: description: Filter by verified status example: true type: boolean description: Common filters for creator discovery 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 FollowersFilter: type: object properties: min: description: Minimum follower count example: 10000 type: number minimum: 0 max: description: Maximum follower count example: 500000 type: number minimum: 0 description: Filter by follower count range EngagementRateFilter: type: object properties: min: description: Minimum engagement rate (%) example: 1.5 type: number minimum: 0 maximum: 100 max: description: Maximum engagement rate (%) example: 10 type: number minimum: 0 maximum: 100 description: Filter by engagement rate range 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' required: - creator - relevant_profile - primary_profile - match additionalProperties: false 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 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 reasons: type: array items: type: string description: Human-readable match reasons example: - Active fitness content creator - High engagement on workout posts required: - score - reasons additionalProperties: false description: Search match information securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````