Please log in to access your API credentials and start using our APIs. Log In & Start Free Trial
Interactive Playground — test this API with real requests and see live responses. Launch Playground
Company APIs

Company Competitor Engagements API

Find people with demonstrated engagement around a company page and return their available profile URLs with post context.

The request is asynchronous and credits are charged per person profile result returned.
Open Playground

Overview

API Endpoint

POST https://api.nyne.ai/company/competitor-engagements
View Markdown llms.txt Agent Manifest
  • Input: A company page URL plus optional result and sorting controls.
  • Delivery: Always asynchronous. Receive a request_id immediately, then poll or register a callback.
  • Output: A results array ordered as person-first engagement items. Each result includes linkedin_profile_url, person details, post date/context, and aggregate engagement details when available.
  • Current employees: People identified as current employees of the requested company are excluded when current organization data is available.
  • Limits: max_items defaults to 100 and can be set from 1 to 100.

Authentication

Authenticate every request with your API key and secret:

Headers 
X-API-Key: your_api_key_hereX-API-Secret: your_api_secret_here

Rate Limits

  • Per Minute: 60 requests
  • Per Hour: 1000 requests
  • Monthly: Varies by plan

Credit Usage

Credits are charged based on the number of person engagement results returned:

  • Company Competitor Engagements: 5 credits per person result returned
  • No Results: No per-result credits are charged if no person profile results are found

POST /company/competitor-engagements

Queue a company competitor engagements request.

POST /company/competitor-engagements

Parameters

company_url (string, required)
Company page URL to analyze
Example: https://www.linkedin.com/company/nyne-ai
max_items (integer, optional)
Maximum number of engagement results to return
Default: 100, Maximum: 100
page_number (integer, optional)
Page number for result pagination
Default: 1
sort (string, optional)
Sort order. Allowed values: recent, top
Default: recent
callback_url (string, optional)
Public HTTP or HTTPS endpoint that receives the completed or failed payload

Request Example

{ "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" }

Response Codes

  • 202: Request queued successfully
  • 400: Missing or invalid request parameters
  • 401: Invalid, missing, or expired API credentials
  • 403: IP, subscription, or credit access denied
  • 429: Rate limit or monthly limit exceeded
  • 500: The request could not be queued

GET /company/competitor-engagements

Retrieve request status and results.

GET /company/competitor-engagements?request_id=

request_id (string, required)
The request ID returned by the POST call
cURL 
curl -X GET "https://api.nyne.ai/company/competitor-engagements?request_id=YOUR_REQUEST_ID" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

Response Format

All responses use the standard Nyne API wrapper.

Queued Response

{ "success": true, "data": { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "queued", "company_url": "https://www.linkedin.com/company/nyne-ai", "max_items": 100, "page_number": 1, "sort": "recent", "message": "Company competitor engagements request queued. Poll this endpoint with GET request_id to retrieve results." }, "timestamp": "2026-04-27T10:00:00Z" }

Completed Response

{ "success": true, "data": { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "completed", "company_url": "https://www.linkedin.com/company/nyne-ai", "max_items": 100, "page_number": 1, "sort": "recent", "completed": true, "results_count": 1, "total_results": 1, "credits_charged": 5, "results": [ { "linkedin_profile_url": "https://www.linkedin.com/in/janedoe", "source_profile_url": "https://www.linkedin.com/in/janedoe", "person": { "linkedin_profile_url": "https://www.linkedin.com/in/janedoe", "profile_url": "https://www.linkedin.com/in/janedoe", "name": "Jane Doe", "display_name": "Jane Doe", "username": "janedoe", "organizations": [ { "name": "Example Software", "title": "Head of Growth" } ] }, "organizations": [ { "name": "Example Software", "title": "Head of Growth" } ], "actor": { "type": "profile", "username": "janedoe", "display_name": "Jane Doe", "name": "Jane Doe", "profile_url": "https://www.linkedin.com/in/janedoe" }, "interaction_id": "7453487458471567360", "interaction_type": "company_post", "interaction_url": "https://www.linkedin.com/posts/example", "interaction_date": "2026-04-24 18:58:09", "date_posted": "2026-04-24 18:58:09", "posted_at": "2026-04-24 18:58:09", "posted_timestamp": 1777057089, "content": { "text": "Example post text", "language_code": "en", "edited": 0 }, "post": { "url": "https://www.linkedin.com/posts/example", "date_posted": "2026-04-24 18:58:09", "type": "repost", "content_preview": "Example post text" }, "target": { "type": "post", "post_type": "repost", "url": "https://www.linkedin.com/posts/example", "author": { "type": "profile", "name": "Jane Doe", "profile_url": "https://www.linkedin.com/in/janedoe" } }, "engagement": { "likes": 22, "comments": 2, "shares": 5, "total_reactions": 26 }, "replies": [] } ], "created_on": "2026-04-27T10:00:00", "completed_on": "2026-04-27T10:00:30" }, "timestamp": "2026-04-27T10:00:35Z" }

Failed Status Response

{ "success": true, "data": { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "failed", "completed": false, "error": "Company competitor engagements request failed. Please try again later." }, "timestamp": "2026-04-27T10:00:35Z" }

Error Codes

  • missing_parameters: company_url is missing
  • invalid_company_url: The supplied URL is not a supported company page URL, or it is a person profile URL
  • invalid_limit: max_items or page_number is not valid
  • invalid_callback_url: Callback URL is not a valid public HTTP or HTTPS URL
  • invalid_json: The request body could not be parsed as JSON
  • missing_request_id: GET status request omitted request_id
  • missing_credentials: POST request did not include API credentials
  • invalid_credentials: POST request credentials are invalid
  • api_key_expired: API key is expired
  • authentication_failed: GET status authentication failed
  • ip_not_allowed: API key is not allowed from this IP address
  • subscription_required: The account subscription does not include this API
  • no_active_subscription: The account does not have an active subscription for this API
  • request_not_found: The request ID does not exist or does not belong to the authenticated API key
  • rate_limit_exceeded: Per-minute or per-hour usage limits were exceeded
  • monthly_limit_exceeded: Monthly usage limit exceeded
  • insufficient_credits: The account does not have enough credits
  • internal_error: The request could not be processed. Try again later.

Callbacks

If callback_url is provided, the API sends one HTTP POST when the request completes or fails. Continue to treat GET status with the returned request_id as the source of truth if your receiver is unavailable.

{ "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "completed", "completed": true, "company_url": "https://www.linkedin.com/company/nyne-ai", "max_items": 100, "page_number": 1, "sort": "recent", "results_count": 1, "credits_charged": 5, "results": [ { "linkedin_profile_url": "https://www.linkedin.com/in/janedoe", "source_profile_url": "https://www.linkedin.com/in/janedoe", "person": { "linkedin_profile_url": "https://www.linkedin.com/in/janedoe", "profile_url": "https://www.linkedin.com/in/janedoe", "name": "Jane Doe", "display_name": "Jane Doe", "organizations": [ { "name": "Example Software", "title": "Head of Growth" } ] }, "organizations": [ { "name": "Example Software", "title": "Head of Growth" } ], "actor": { "type": "profile", "username": "janedoe", "display_name": "Jane Doe", "name": "Jane Doe", "profile_url": "https://www.linkedin.com/in/janedoe" }, "interaction_id": "7453487458471567360", "interaction_type": "company_post", "interaction_url": "https://www.linkedin.com/posts/example", "date_posted": "2026-04-24 18:58:09", "posted_timestamp": 1777057089, "post": { "url": "https://www.linkedin.com/posts/example", "date_posted": "2026-04-24 18:58:09" }, "content": { "text": "Example post text" }, "engagement": { "likes": 22, "comments": 2, "shares": 5 }, "replies": [] } ], "completed_on": "2026-04-27T10:00:30" }

Open Playground