# Competitor Engagements > Find people who engaged with a company page, with profile URLs and post context. - **Endpoint:** `POST https://api.nyne.ai/company/competitor-engagements` - **Group:** Company APIs (https://api.nyne.ai/documentation/company.md) - **Auth:** `X-API-Key` + `X-API-Secret` headers - **Mode:** Asynchronous — submit returns `202 Accepted` with a `request_id`; poll `GET /company/competitor-engagements?request_id=` (same auth headers) until `status` is `completed`, or supply a `callback_url` to receive the result by webhook. - **HTML version:** https://api.nyne.ai/documentation/company/competitor Find people who have demonstrated engagement around a company page and return their available profile URLs with post context. Supply a `company_url` plus optional result and sorting controls. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url`. Results are person-first engagement items with `linkedin_profile_url`, person details, post date/context, and aggregate engagement metrics; people identified as current employees of the requested company are excluded when current-organization data is available. Credits are charged per person engagement result returned. ## 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 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 | | --- | --- | --- | --- | --- | | `company_url` | string | **yes** | Company page URL to analyze. Must be a supported company page, not a person profile URL. | "https://www.linkedin.com/company/nyne-ai" | | `max_items` | integer | no | Maximum engagement results to return. Range 1–100, default 100. | 100 | | `page_number` | integer | no | Page number for result pagination. Default 1. | 1 | | `sort` | string | no | Sort order — `recent` (default) or `top`. | "recent" | | `callback_url` | string | no | Public http(s) endpoint that receives the completed or failed payload. Localhost / private-network targets are rejected. | "https://example.com/webhook/company-engagements" | ## Polling for the result The submit returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards), or pass a `callback_url` on the submit to receive the completed result by webhook instead: ```bash curl "https://api.nyne.ai/company/competitor-engagements?request_id=" \ -H "X-API-Key: nyne_live_a17f…3c9b" \ -H "X-API-Secret: nyne_sec_••••••••" ``` ## Credit usage | Item | Credits | Condition | | --- | --- | --- | | Competitor Engagements | 5 | Charged per person engagement result returned (per-result) | | No results | 0 | No person profile results never burns per-result credits | ## Responses | Code | Meaning | | --- | --- | | `202` | Request queued — poll the status endpoint with the returned request_id | | `400` | missing_parameters / invalid_company_url / invalid_limit / invalid_callback_url / invalid_json | | `401` | missing_credentials / invalid_credentials / api_key_expired | | `403` | ip_not_allowed, subscription_required, no_active_subscription, or insufficient_credits | | `404` | request_not_found (on status poll) | | `429` | rate_limit_exceeded / monthly_limit_exceeded | | `500` | internal_error — the request could not be queued | ## Example request ### cURL ```bash curl -X POST https://api.nyne.ai/company/competitor-engagements \ -H "X-API-Key: nyne_live_a17f…3c9b" \ -H "X-API-Secret: nyne_sec_••••••••" \ -H "Content-Type: application/json" \ -d '{ "company_url": "https://www.linkedin.com/company/nyne-ai", "max_items": 100, "page_number": 1, "sort": "recent", "callback_url": "https://example.com/webhook/company-engagements" }' ``` ### Python ```python import requests resp = requests.post( "https://api.nyne.ai/company/competitor-engagements", headers={ "X-API-Key": "nyne_live_a17f…3c9b", "X-API-Secret": "nyne_sec_••••••••", }, json={ "company_url": "https://www.linkedin.com/company/nyne-ai", "max_items": 100, "page_number": 1, "sort": "recent", "callback_url": "https://example.com/webhook/company-engagements", }, ) data = resp.json() print(data) ``` ### Node ```javascript const resp = await fetch("https://api.nyne.ai/company/competitor-engagements", { method: "POST", headers: { "X-API-Key": "nyne_live_a17f…3c9b", "X-API-Secret": "nyne_sec_••••••••", "Content-Type": "application/json", }, body: JSON.stringify({ company_url: "https://www.linkedin.com/company/nyne-ai", max_items: 100, page_number: 1, sort: "recent", callback_url: "https://example.com/webhook/company-engagements", }), }); const data = await resp.json(); console.log(data); ``` ### PHP ```php true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "X-API-Key: nyne_live_a17f…3c9b", "X-API-Secret: nyne_sec_••••••••", "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "company_url" => "https://www.linkedin.com/company/nyne-ai", "max_items" => 100, "page_number" => 1, "sort" => "recent", "callback_url" => "https://example.com/webhook/company-engagements", ]), ]); $data = json_decode(curl_exec($ch), true); print_r($data); ``` ## Example response ```json { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a_1700000123_8810", "status": "completed", "completed": true, "result": { "results": [ { "linkedin_profile_url": "https://www.linkedin.com/in/janedoe", "person": { "name": "Jane Doe", "organizations": [ { "name": "Example Software", "title": "Head of Growth" } ] }, "interaction_type": "company_post", "post_date": "2026-01-10T15:30:00Z", "engagement_metrics": { "likes": 24, "comments": 3, "shares": 1 } } ], "total_results": 1 }, "completed_on": "2026-01-15T10:35:00Z" } ``` --- All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt