Company APIs

Competitor Engagements

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.

POST https://api.nyne.ai/company/competitor-engagements API key

Try it needs this required parameter:

Overview

Find people who engaged with a company page, with profile URLs and post context.

Parameters

company_url string required

Company page URL to analyze. Must be a supported company page, not a person profile URL.

max_items integer optional

Maximum engagement results to return. Range 1–100, default 100.

page_number integer optional

Page number for result pagination. Default 1.

sort string optional

Sort order — recent (default) or top.

callback_url string optional

Public http(s) endpoint that receives the completed or failed payload. Localhost / private-network targets are rejected.

Polling for the result

This endpoint is asynchronous. A successful submit returns 202 with a request_id while the job runs in the background. Poll the same path with a GET request — same authentication headers — passing the request_id as a query parameter:

curl "https://api.nyne.ai/company/competitor-engagements?request_id=<request_id>" \
  -H "X-API-Key: nyne_live_a17f…3c9b" \
  -H "X-API-Secret: nyne_sec_••••••••"

Each poll returns the job's current status; once it is completed the payload carries the result shown under Responses. Polling an unknown or expired request_id returns 404 request_not_found.

Status	Meaning
queued · processing · pending	The job is still running — keep polling.
completed	The job finished; the payload carries the result and completed: true.
failed	Terminal — the job could not complete; the error field explains why.

Poll every few seconds at first, backing off for long-running jobs. Polling is free — status checks never burn credits.

Prefer push delivery?

Supply the optional callback_url parameter and the completed payload is POSTed to your endpoint when the job finishes — no polling required.

Credit usage

Credits are charged based on the matched configuration. The listed cost is the per-result unit price.

Feature	Credits	Notes
Competitor Engagements	5	Charged per person engagement result returned (per-result)
No results	0	No person profile results never burns per-result credits

Heads up

A positive credit balance is required before each request. Empty results do not burn credits.

Responses

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

A successful response wraps the payload in the { success, data, timestamp } envelope (also shown live in the panel on the right):

{
  "success": true,
  "data": {
    "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"
  },
  "timestamp": "2026-06-12T11:04:12"
}