# Company Search > Find companies from a natural-language query. - **Endpoint:** `POST https://api.nyne.ai/company/search` - **Group:** Company APIs (https://api.nyne.ai/documentation/company.md) - **Auth:** `X-API-Key` + `X-API-Secret` headers - **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/search?request_id=` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes. - **HTML version:** https://api.nyne.ai/documentation/company/search Discover companies using the same freeform search style as `person/search`. Send a natural-language `query` such as “pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees”. When a query ties a funding stage, amount, date, or investor to one round, those constraints must match the same funding event. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url` to receive the completed result. Completed results use the same page envelope: `results`, `returned_count`, `total_results`, `total_relation`, `limit`, `offset`, `has_more`, and `next_offset`. Use `profile_scoring` to add a 1-5 relevance `score`, and `insights` to add query-fit explanations. Credits are charged per company returned, so an empty result burns nothing. ## Authentication All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md ## Parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `query` | string | **yes** | Natural-language company search request. The backend interprets industries, locations, employee counts, follower counts, founded years, web/LinkedIn presence, funding, investors, organization type, technologies used (technographics), acquisition status, physical location count, and investor-firm criteria (VC/fund, stages they invest in, check size) when present. Funding facts tied to one round are evaluated against the same funding event. Max 700 chars. | "insurance companies without a website in California with less than 10 employees" | | `limit` | integer | no | Maximum companies to return. Range 1-50, default 10. | 10 | | `offset` | integer | no | Starting position for offset pagination (0-indexed). Default 0; `offset` + `limit` may not exceed 10000. To retrieve another page, submit the same `query` with the `next_offset` from the previous completed response. | 0 | | `profile_scoring` | boolean | no | When true, completed company rows include `score`, an AI-generated 1-5 relevance score for the query. Defaults to false. | true | | `insights` | boolean | no | When true, completed company rows include `insights` with query-fit evidence chips and concise rationales. Defaults to false. | true | | `callback_url` | string | no | http(s) URL on an allowed host that receives the completed payload automatically. | "https://example.com/webhooks/company-search" | ## Polling for the result A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path: ```bash curl "https://api.nyne.ai/company/search?request_id=" \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" ``` ## Pagination A completed company search returns one offset-based page. Use `next_offset` from a completed response as the `offset` on a new `POST /company/search` with the same query to request the next page. Polling an existing `request_id` is for checking completion or re-reading the stored page; it does not launch a new billable search page. ### Knowing when to paginate | Response field | Meaning | | --- | --- | | has_more | `true` means more results may be available beyond this page. | | next_offset | The offset to request for the next page. Present only when `has_more` is `true`. | | total_results | Exact match count when `total_relation` is `eq`; a lower bound when `total_relation` is `gte`. | ### Fetching the next page | Method | How | | --- | --- | | Repeat the query + offset | Submit the same `query` with a higher `offset` to retrieve another page. | | request_id polling | Use `GET /company/search?request_id=...` to poll status or re-read the stored page for that request. Optional `limit`/`offset` only slice the stored page when the requested slice overlaps it. | ## Credit usage | Item | Credits | Condition | | --- | --- | --- | | Company Search | 1 | Charged per company returned (per-result) | | No match | 0 | Empty results never burn credits | ## Responses | Code | Meaning | | --- | --- | | `202` | Search queued - poll the status endpoint with the returned request_id | | `400` | missing_parameters / invalid_parameters / invalid_limit / invalid_callback_url | | `401` | Missing or invalid API credentials | | `402` | insufficient_credits - returned when a queued request cannot continue because credits are unavailable | | `403` | subscription_required or ip_not_allowed | | `429` | rate_limit_exceeded / monthly_limit_exceeded | | `503` | service_unavailable - the API is temporarily unavailable | ## Example request ### cURL ```bash curl -X POST https://api.nyne.ai/company/search \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "query": "pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees", "limit": 10, "offset": 0, "profile_scoring": true, "insights": true }' ``` ### Python ```python import requests resp = requests.post( "https://api.nyne.ai/company/search", headers={ "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", }, json={ "query": "pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees", "limit": 10, "offset": 0, "profile_scoring": True, "insights": True, }, ) data = resp.json() print(data) ``` ### Node ```javascript const resp = await fetch("https://api.nyne.ai/company/search", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json", }, body: JSON.stringify({ query: "pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees", limit: 10, offset: 0, profile_scoring: true, insights: true, }), }); const data = await resp.json(); console.log(data); ``` ### PHP ```php true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "X-API-Key: YOUR_API_KEY", "X-API-Secret: YOUR_API_SECRET", "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "query" => "pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees", "limit" => 10, "offset" => 0, "profile_scoring" => true, "insights" => true, ]), ]); $data = json_decode(curl_exec($ch), true); print_r($data); ``` ## Example response ```json { "request_id": "cosearch_64f2d8e4_1700000123", "status": "completed", "completed": true, "results": [ { "profile_id": "nyne-ai", "name": "Nyne.ai", "display_name": "Nyne.ai", "url": "nyne.ai", "website_url": "nyne.ai", "domain": "nyne.ai", "linkedin_url": "linkedin.com/company/nyne-ai", "linkedin_id": "99082053", "linkedin_slug": "nyne-ai", "industry": "software development", "organization_type": "privately held", "employee_count": 12, "employee_count_range": { "start": 11, "end": 50 }, "follower_count": 1172, "founded_year": 2024, "company_size_label": "11-50", "total_funding_raised": 1000000, "latest_funding_stage": "pre seed", "funding_stages": [ "pre seed" ], "funding_rounds": [ { "stage": "pre seed", "date": "2025-10-03", "amount": 1000000, "investor_names": [ "south park commons" ] } ], "last_funding_date": "2025-10-03", "last_funding_round_url": "crunchbase.com/funding_round/nyne-ai-pre-seed--78449dc7", "number_funding_rounds": 1, "investor_names": [ "south park commons" ], "investor_count": 1, "is_acquired": false, "technologies": [ "salesforce", "amazon web services" ], "product_types": [ "crm" ], "tech_categories": [ "crm software" ], "has_technographics": true, "specialities": [ "ai infrastructure", "developer tools" ], "location_count": 2, "is_investor": false, "invests_in_stages": [], "headquarter": { "city": "san francisco", "region": "ca", "country": "us", "country_iso": "US" }, "score": 5, "insights": { "overall_summary": "Strong match: pre-seed software company backed by the requested investor.", "why_matched": [ { "criterion": "Funding stage match", "evidence_type": "funding", "confidence": "strong", "display_text": "Latest funding stage is pre seed.", "matched_phrase": "pre seed" }, { "criterion": "Investor match", "evidence_type": "investor", "confidence": "strong", "display_text": "Investor list includes South Park Commons.", "matched_phrase": "south park commons" } ], "query_insights": [ { "subquery_idx": 0, "subquery": "pre-seed software company", "priority": "Essential", "match_level": "Meets Expectations", "short_rationale": "Company has a pre seed funding stage.", "rationale": "The company is listed with latest funding stage pre seed.", "short_quotes": [ "pre seed" ] } ] } } ], "returned_count": 1, "total_results": 1, "total_relation": "eq", "limit": 10, "offset": 0, "has_more": false, "next_offset": null } ``` --- All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt