> ## 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. # Quickstart > Search for creators, fetch a creator record, and understand billing in under five minutes # Quickstart By the end of this page, you'll have searched for creators, fetched a full creator record, and inspected the usage headers on both requests. ## Install and configure Install the SDK and set your API key as an environment variable. ```bash npm theme={null} npm install influship ``` ```bash pnpm theme={null} pnpm add influship ``` ```bash yarn theme={null} yarn add influship ``` ```bash theme={null} export INFLUSHIP_API_KEY="your_api_key_here" ``` If you prefer raw HTTP, skip the install -- you only need the API key in the `X-API-Key` header. For details on key management, scopes, and rotation, see the [Authentication guide](/guides/authentication). Never commit API keys to version control. Use environment variables or a secrets manager. ## Search for creators Search is the primary discovery endpoint. You pass a natural-language query describing the kind of creator you need, and the API returns ranked matches with scores and explanations. The `query` field accepts up to 500 characters of free text. The `limit` sets the maximum number of results for that search session. ```typescript SDK theme={null} import Influship from 'influship'; const client = new Influship({ apiKey: process.env.INFLUSHIP_API_KEY, }); const response = await client.search.create({ query: 'fitness creators focused on home workouts, consistent posting schedule', limit: 5, platforms: ['instagram'], filters: { followers: { min: 50000 }, engagement_rate: { min: 2.0 }, }, }); console.log(response); ``` ```bash cURL theme={null} curl -X POST https://api.influship.com/v1/search \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "fitness creators focused on home workouts, consistent posting schedule", "limit": 5, "filters": { "followers": { "min": 50000 }, "engagement_rate": { "min": 2.0 } }, "platforms": ["instagram"] }' ``` Filters are optional but useful for narrowing results. Available filter fields: | Filter | Type | Description | | --------------------------------------------- | --------- | ------------------------------------------------ | | `followers.min` / `followers.max` | integer | Follower count range | | `engagement_rate.min` / `engagement_rate.max` | number | Engagement rate as percentage (2.0 = 2%) | | `verified` | boolean | Only verified accounts | | `platforms` (top-level) | string\[] | Platforms to search, defaults to `["instagram"]` | ## Inspect the response Here's an abbreviated version of what comes back: ```json theme={null} { "data": [ { "creator": { "id": "a3f1b9c2-7d4e-4a8f-b6e1-2c9d5f8a0b3e", "name": "Alex Rivera" }, "relevant_profile": { "platform": "instagram", "username": "alexrivera.fit" }, "primary_profile": { "platform": "instagram", "username": "alexrivera.fit" }, "match": { "score": 0.91, "reasons": [ "Consistent home workout content with strong audience engagement" ] } }, { "creator": { "id": "d7e4c1a8-3b2f-49d6-8e5c-1a7f3b9d2e6c", "name": "Maya Chen" }, "relevant_profile": { "platform": "instagram", "username": "mayachen.fitness" }, "primary_profile": { "platform": "instagram", "username": "mayachen.fitness" }, "match": { "score": 0.87, "reasons": [ "Home fitness tutorials with high save rate and comment engagement" ] } } ], "search_id": "8f3a1b2c-4d5e-4678-9abc-1234567890de", "total": 2, "has_more": false, "next_cursor": null } ``` A few fields worth noting: * **`creator`** -- the canonical creator record. The `id` is what you use to fetch full profiles and pass to other endpoints. * **`relevant_profile`** -- the profile most relevant to the query, or `null` when no profile data is available. * **`primary_profile`** -- the creator's largest profile, or `null` when no profile data is available. * **`match.score`** -- a 0-to-1 relevance score. Higher means a closer fit to your query. Scores above 0.8 are typically strong matches. * **`match.reasons`** -- human-readable explanations of why the creator matched. Useful for displaying to end users or for your own review. Search accepts natural language. If your end users aren't marketers, consider preprocessing their input with an LLM to improve result quality. Test both approaches -- sometimes raw user input works fine, sometimes a refinement step makes a real difference. The [API Reference](/api-reference) is the source of truth for exact response shapes, required fields, and edge cases. The examples on this page are abbreviated for clarity. ## Fetch a creator by ID Use the `id` from a search result to pull the full creator record. Add `?include=profiles` to expand linked social profiles in the same response, so you don't need a separate call for each platform. ```typescript SDK theme={null} const creator = await client.creators.retrieve( 'a3f1b9c2-7d4e-4a8f-b6e1-2c9d5f8a0b3e', { include: ['profiles'] } ); console.log(creator); ``` ```bash cURL theme={null} curl "https://api.influship.com/v1/creators/a3f1b9c2-7d4e-4a8f-b6e1-2c9d5f8a0b3e?include=profiles" \ -H 'X-API-Key: YOUR_API_KEY' ``` The response includes the creator's metadata and an array of linked profile summaries with usernames, follower counts, engagement rates, and verification status. ## Check cost and remaining budget Every response includes billing and rate-limit headers. After the search request above, you'd see something like: ```http theme={null} X-Credits-Charged: 35.00 X-Credits-Features: creators.search X-Billing-Plan: free RateLimit-Remaining-Minute: 115 RateLimit-Remaining-Hour: 1465 ``` Search billing breaks down like this: | Component | Cost | | --------------------- | -------------------------------------------------------------------------------------------------- | | Base fee per search | 25 credits | | Per creator delivered | 2 credits | The base fee covers the AI inference that runs on every query. The per-creator fee scales with how many results you actually receive. With `limit: 5` and five results returned, that's 25 + (5 x 2) = **35 credits**, or **\$0.35**. If the API only finds 3 matches, you'd pay 25 + (3 x 2) = 31 credits -- you're never charged for results that don't exist. The `RateLimit-Remaining-*` headers tell you how many rate-limit credits remain in the current window. Monitor these if you're running batch searches. See [Pricing](/concepts/pricing) for full cost rules and [Rate Limits & Tiers](/concepts/quotas-and-limits) for current budgets by plan. ## Next steps Understand the data model and when to use each resource Query syntax, scoring, and how to get the best results Typed client setup, error handling, and pagination Full endpoint specs with generated examples for every route