# Person Newsfeed API
> Get someone's recent social media posts across major platforms
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/newsfeed`

---

## Overview
The Person Newsfeed API lets you retrieve someone's recent social media posts across major platforms. Provide any social media profile URL and get back that person's recent posts, updates, and activity. See what they've been sharing, what topics they're discussing, and how their audience is engaging.
### What You Get
- **Social Media Posts:** Recent posts, updates, and shared content from profiles- **Engagement Metrics:** Likes, comments, shares, and other interaction data- **Multi-Platform Support:** LinkedIn, Twitter/X, Instagram, GitHub, and Facebook- **Post Metadata:** Timestamps, post types, and content details- **Profile Info:** Source platform, username, and profile URL
## 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

- **Newsfeed Request:** 6 credits 2 credits per 10 posts returned (rounded up)
> Credits scale with the number of posts returned: 2 credits per 10 posts (rounded up). Examples: 1-10 posts = 2 credits, 15 posts = 4 credits, 100 posts = 20 credits. If no posts are found, no credits are charged. Your account is pre-checked for worst-case cost based on the requested limit before processing begins.
---

## POST /person/newsfeedFetch newsfeed data from a social media profile.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `social_media_url` | string | Yes | Social media profile URL to fetch newsfeed from |
| `callback_url` | string | No | URL to receive results asynchronously |
| `limit` | integer | No | Maximum number of the most recent posts to return (newest first). Min: 1, Max: 1000. Default: 10. Credit cost scales with results: 2 credits per 10 posts (rounded up). |
| `posts_after` | string | No | Only return posts published on or after this date. Format: YYYY-MM-DD. Posts without a parseable date are included. |

> **Required:** social_media_url is required.
### Request Examples

**With Advanced Features:**

```json
{
  "social_media_url": "https://linkedin.com/in/johndoe",
  "callback_url": "https://yourapp.com/webhook/newsfeed",
  "limit": 25,
  "posts_after": "2025-01-01"
}
```

**Basic Request:**

```json
{
  "social_media_url": "https://linkedin.com/in/johndoe"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/newsfeed \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://linkedin.com/in/username",
    "callback_url": "https://yourapp.com/webhook/newsfeed",
    "limit": 25,
    "posts_after": "2025-01-01"
  }'
```

**Python:**

```python
import requests
import json

url = "https://api.nyne.ai/person/newsfeed"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
}

data = {
    "social_media_url": "https://linkedin.com/in/username",
    "callback_url": "https://yourapp.com/webhook/newsfeed",
    "limit": 25,
    "posts_after": "2025-01-01"
}

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/newsfeed";
const headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
};

const data = {
    social_media_url: "https://linkedin.com/in/username",
    callback_url: "https://yourapp.com/webhook/newsfeed",
    limit: 25,
    posts_after: "2025-01-01"
};

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
<?php
$url = "https://api.nyne.ai/person/newsfeed";
$headers = [
  "X-API-Key: YOUR_API_KEY",
  "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];

$data = [
    "social_media_url" => "https://linkedin.com/in/username",
    "callback_url" => "https://yourapp.com/webhook/newsfeed",
    "limit" => 25,
    "posts_after" => "2025-01-01"
];

$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 |
|------|-------------|
| 200 | Newsfeed request accepted successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "newsfeed_d5b4252d9c909936_1759543380_9975",
    "status": "pending",
    "message": "Newsfeed request has been queued for processing. Results will be sent to your callback URL."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
```

---

## GET /person/newsfeed
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/newsfeed?request_id=abc123def456
```

### 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": "newsfeed_d5b4252d9c909936_1759543380_9975",
    "status": "completed",
    "completed": true,
    "result": {
      "newsfeed": [
        {
          "id": "post_123",
          "content": "Excited to announce our new product launch!",
          "timestamp": "2024-01-14T15:30:00Z",
          "likes": 45,
          "comments": 12,
          "shares": 8,
          "post_type": "text"
        }
      ],
      "source": "linkedin",
      "username": "johndoe",
      "url": "https://linkedin.com/in/johndoe"
    },
    "error": null,
    "created_on": "2024-01-15T10:30:00Z",
    "completed_on": "2024-01-15T10:35:00Z"
  },
  "timestamp": "2024-01-15T10:35:00Z"
}
```

---

## 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- The status field indicates the processing state: pending, processing, or completed- The newsfeed array contains post objects with content, timestamps, and engagement metrics- Engagement fields vary by platform (e.g., shares on LinkedIn, retweets on Twitter)- If a field has no data, it will be omitted from the response
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | Required parameters are missing |
| 400 | `invalid_url` | Invalid or unsupported social media URL |
| 400 | `invalid_callback_url` | Invalid callback URL format |
| 400 | `invalid_parameter` | Invalid parameter value (e.g., limit out of range, invalid date format) |
| 400 | `missing_request_id` | Request ID is required for status checks |
| 401 | `missing_credentials` | API key is missing from request |
| 401 | `invalid_credentials` | API key is invalid or expired |
| 403 | `ip_not_allowed` | Request IP address is not in this key's Allowed IPs list |
| 403 | `subscription_required` | Your subscription does not include newsfeed access |
| 402 | `insufficient_credits` | Not enough credits for the requested limit |
| 404 | `request_not_found` | Request ID not found |
| 429 | `rate_limit_exceeded` | Rate limit exceeded |
| 429 | `monthly_limit_exceeded` | Monthly request 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- Maximum 5 retry attempts with exponential backoff- Your endpoint must respond with HTTP 200 OK- Response time should be under 30 seconds- Include proper error handling in your endpoint
Your callback endpoint should respond with HTTP 200-299. Any other code triggers a retry.

### Callback Payload Example

```json
{
  "request_id": "abc123def456",
  "status": "completed",
  "newsfeed": {
    "platform": "linkedin",
    "profile_url": "https://linkedin.com/in/johndoe",
    "posts": [...],
    "total_posts": 5
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **Use Profile URLs** (Best) — Provide the full social media profile URL for most reliable results.2. **Use Callbacks** (Recommended) — Provide a callback_url to receive results asynchronously rather than polling.
---

## Note for AI Agents
This is an asynchronous API. Submit via POST, then poll the GET endpoint with the returned request_id until status is completed. Typical processing time is 10-60 seconds. Use callback_url for production workflows to avoid polling overhead.
---

## Related APIs
- **Social Profiles API** — Find social accounts to monitor → `https://api.nyne.ai/documentation/person/social-profiles`
- **Social Interactions API** — Analyze social engagement patterns → `https://api.nyne.ai/documentation/person/interactions`
- **Personal Interests API** — Discover interests from social graph → `https://api.nyne.ai/documentation/person/interests`