# Competitor Engagements API > Discover what content a LinkedIn profile has engaged with - track comments, reactions, and interactions to identify leads and monitor competitor activity **Base URL:** `https://api.nyne.ai` **Endpoint:** `https://api.nyne.ai/person/competitor-engagements` --- ## Overview The Competitor Engagements API lets you discover what content a LinkedIn profile has been engaging with. By providing a LinkedIn profile URL, you can track their recent comments, reactions, and interactions on posts - useful for identifying leads, monitoring competitor activity, and understanding who your competitors are talking to. **Use Cases:** - **Lead Generation:** Identify people engaging with your competitors' content - **Competitive Intelligence:** Monitor what content competitors are engaging with - **Sales Prospecting:** Find warm leads by tracking engagement with relevant industry content - **Content Strategy:** Understand what topics resonate with target audiences **How It Works:** **Input:** Provide one or more LinkedIn profile URLs (up to 50 per request) **Output:** Receive a list of recent interactions (comments, reactions) with details about each engagement ### What You Get - **Comments:** Text comments the profile has made on posts- **Reactions:** Posts the profile has liked or reacted to- **Interaction Details:** Post content, author info, and engagement metrics- **Target Information:** Details about the posts and authors they engaged with- **Timestamps:** When each interaction occurred ## Authentication All requests require header authentication: ``` X-API-Key: YOUR_API_KEY X-API-Secret: YOUR_API_SECRET ``` ## Rate Limits | Limit | Value | |-------|-------| | Per Minute | 60 requests | | Per Hour | 1000 requests | | Monthly | Varies by plan | ### Response Headers Responses from endpoints that perform rate-limit checks include both legacy and standard rate-limit headers: | Header | Description | |--------|-------------| | `X-RateLimit-Limit` | Active per-minute or per-hour limit | | `X-RateLimit-Remaining` | Remaining requests in the active window | | `X-RateLimit-Reset` | Unix timestamp when the active window resets | | `RateLimit-Limit` | Active per-minute or per-hour limit | | `RateLimit-Remaining` | Remaining requests in the active window | | `RateLimit-Reset` | Seconds until the active window resets | | `Retry-After` | Seconds to wait before retrying; present on HTTP `429` rate-limit responses | Monthly quota responses include quota-specific headers when available: | Header | Description | |--------|-------------| | `X-Quota-Limit` | Monthly request or credit limit | | `X-Quota-Used` | Amount used in the current billing cycle | | `X-Quota-Remaining` | Amount remaining in the current billing cycle | | `X-Quota-Reset` | Unix timestamp when the current billing cycle resets | ## Credit Usage - **Per Engagement Result:** credits per interaction returned > Credits are only charged when engagement results are returned. If no engagements are found for a profile, no credits are charged. Example: if the API returns 15 engagement interactions, you will be charged 15 x the per-result credit cost. --- ## POST /person/competitor-engagementsSubmit a request to retrieve competitor engagement data for one or more LinkedIn profiles. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `linkedin_urls` | array of strings | Yes | Array of LinkedIn profile URLs to analyze (maximum 50 URLs per request). If more than 50 URLs are provided, only the first 50 will be processed. | | `max_items` | integer | No | Maximum number of engagement results to return per profile (default: `20`) | | `callback_url` | string | No | URL to receive results asynchronously when processing completes | > **Required:** The linkedin_urls parameter is required and must contain at least one valid LinkedIn profile URL. ### Request Examples **With Advanced Features:** ```json { "linkedin_urls": [ "https://www.linkedin.com/in/johndoe", "https://www.linkedin.com/in/janesmith" ], "max_items": 20, "callback_url": "https://yourapp.com/webhook/engagements" } ``` **Basic Request:** ```json { "linkedin_urls": [ "https://www.linkedin.com/in/johndoe" ] } ``` ### Code Examples **cURL:** ```bash curl -X POST https://api.nyne.ai/person/competitor-engagements \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "linkedin_urls": [ "https://www.linkedin.com/in/johndoe", "https://www.linkedin.com/in/janesmith" ], "max_items": 20 }' ``` **Python:** ```python import requests import json url = "https://api.nyne.ai/person/competitor-engagements" headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" } data = { "linkedin_urls": [ "https://www.linkedin.com/in/johndoe", "https://www.linkedin.com/in/janesmith" ], "max_items": 20 } response = requests.post(url, headers=headers, json=data) result = response.json() print(json.dumps(result, indent=2)) ``` **JavaScript:** ```javascript const url = "https://api.nyne.ai/person/competitor-engagements"; const headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" }; const data = { linkedin_urls: [ "https://www.linkedin.com/in/johndoe", "https://www.linkedin.com/in/janesmith" ], max_items: 20 }; fetch(url, { method: "POST", headers: headers, body: JSON.stringify(data) }) .then(response => response.json()) .then(result => console.log(result)) .catch(error => console.error("Error:", error)); ``` **PHP:** ```php [ "https://www.linkedin.com/in/johndoe", "https://www.linkedin.com/in/janesmith" ], "max_items" => 20 ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $result = json_decode($response, true); curl_close($ch); echo json_encode($result, JSON_PRETTY_PRINT); ?> ``` ### Response Codes | Code | Description | |------|-------------| | 202 | Request accepted and queued for processing | | 400 | Invalid request parameters | | 401 | Invalid API credentials | | 402 | Insufficient credits | | 429 | Rate limit exceeded | ### Response Example ```json { "success": true, "data": { "request_id": "a1b2c3d4e5f6...", "status": "pending", "linkedin_urls": [ "https://www.linkedin.com/in/johndoe", "https://www.linkedin.com/in/janesmith" ], "url_count": 2, "max_items": 20, "message": "Competitor engagements request queued. Use GET /person/competitor-engagements?request_id=... to check status." }, "timestamp": "2026-01-22T10:00:00Z" } ``` --- ## GET /person/competitor-engagements Check the status of a request. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `request_id` | string | Yes | The request ID returned from the POST request | ### Request Example ``` GET /person/competitor-engagements?request_id=a1b2c3d4e5f6... ``` ### Response Codes | Code | Description | |------|-------------| | 200 | Status retrieved successfully | | 400 | Invalid request parameters | | 401 | Invalid API credentials | | 404 | Request ID not found | ### Response Example ```json { "success": true, "data": { "request_id": "a1b2c3d4e5f6...", "status": "completed", "linkedin_urls": [ "https://www.linkedin.com/in/johndoe", "https://www.linkedin.com/in/janesmith" ], "url_count": 2, "completed": true, "results_count": 15, "credits_charged": 75, "results": [ { "interaction_id": "7418464047378903040", "interaction_type": "comment", "interaction_url": "https://www.linkedin.com/feed/update/urn:li:activity:7418464047378903040", "interaction_date": "2026-01-18T01:27:37.292Z", "linkedin_profile_url": "https://www.linkedin.com/in/johndoe", "source_profile_url": "https://www.linkedin.com/in/johndoe", "actor": { "type": "profile", "display_name": "John Doe", "profile_url": "https://www.linkedin.com/in/johndoe" }, "content": { "text": "Great insights on the future of AI! Really appreciate the thoughtful analysis." }, "target": { "type": "post", "author": { "name": "Tech Company", "type": "company", "profile_url": "https://www.linkedin.com/company/techcompany/" } }, "engagement": { "likes": 12, "comments": 3 }, "replies": [] }, { "interaction_id": "7417892345678901234", "interaction_type": "reaction", "interaction_url": "https://www.linkedin.com/feed/update/urn:li:activity:7417892345678901234", "interaction_date": "2026-01-17T14:15:22.000Z", "linkedin_profile_url": "https://www.linkedin.com/in/janesmith", "source_profile_url": "https://www.linkedin.com/in/janesmith", "actor": { "type": "profile", "display_name": "Jane Smith", "profile_url": "https://www.linkedin.com/in/janesmith" }, "target": { "type": "post", "author": { "name": "Jane Smith", "type": "person", "profile_url": "https://www.linkedin.com/in/janesmith/" } }, "engagement": { "likes": 245, "comments": 42 }, "replies": [] } ], "created_on": "2026-01-22T10:00:00Z", "completed_on": "2026-01-22T10:00:30Z" }, "timestamp": "2026-01-22T10:00:35Z" } ``` --- ## Response Format All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available: - All API responses follow a consistent JSON format with success, data, and timestamp fields- The results array contains interaction objects, each with interaction_id, interaction_type, interaction_url, and interaction_date- Each result includes linkedin_profile_url, source_profile_url, and actor fields for the profile that made the interaction when available- The content object is only present for comment-type interactions- The target object contains information about the post and its author- The engagement object contains metrics (likes, comments) for the target content --- ## Error Codes | HTTP Code | Error Code | Description | |-----------|------------|-------------| | 400 | `missing_parameters` | Required linkedin_urls parameter is missing or empty | | 400 | `invalid_linkedin_url` | One or more URLs are not valid LinkedIn profile URLs | | 400 | `invalid_callback_url` | The callback URL is not a valid HTTP/HTTPS URL | | 400 | `invalid_limit` | max_items is not valid | | 400 | `invalid_json` | The request body could not be parsed as JSON | | 401 | `invalid_credentials` | API key or secret is incorrect | | 402 | `insufficient_credits` | Not enough credits to process the request | | 404 | `not_found` | Request ID not found | | 429 | `rate_limit_exceeded` | Rate limit exceeded | | 500 | `internal_error` | Internal server error | --- ## Callbacks When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST. ### Retry Policy- 30-second timeout per request- Your endpoint should return HTTP 2xx for success Your callback endpoint should respond with HTTP 200-299. Any other code triggers a retry. ### Callback Payload Example ```json { "request_id": "a1b2c3d4e5f6...", "status": "completed", "completed": true, "linkedin_urls": [ "https://www.linkedin.com/in/johndoe", "https://www.linkedin.com/in/janesmith" ], "url_count": 2, "results_count": 15, "credits_charged": 75, "results": [ { "interaction_id": "7418464047378903040", "interaction_type": "comment", "interaction_date": "2026-01-18T01:27:37.292Z", "linkedin_profile_url": "https://www.linkedin.com/in/johndoe", "source_profile_url": "https://www.linkedin.com/in/johndoe", "actor": { "type": "profile", "display_name": "John Doe", "profile_url": "https://www.linkedin.com/in/johndoe" }, "content": { "text": "Great insights!" }, "target": { "type": "post", "author": { "name": "Tech Company" } }, "engagement": { "likes": 12, "comments": 3 }, "replies": [] } ], "completed_on": "2026-01-22T10:00:30Z" } ``` --- ## Related APIs - **Social Interactions API** - Social network analysis -> `https://api.nyne.ai/documentation/person/interactions` - **Social Newsfeed API** - Get social media posts -> `https://api.nyne.ai/documentation/person/newsfeed` - **Person Enrichment API** - Enrich engaged profiles -> `https://api.nyne.ai/documentation/person/enrichment`