# Person Interactions API
> Fetch social interaction data including post replies, followers, and following lists from supported social media profiles
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/interactions`

---

## Overview
The Person Interactions API allows you to fetch social interaction data from supported social media profiles. This includes people who replied to specific posts, account followers, and accounts a user follows. The API supports Twitter/X and Instagram, with automatic URL parsing and asynchronous callback support for high-volume operations.
### What You Get
- **Post Replies:** Get users who replied to a specific post- **Followers:** Retrieve a list of people following an account- **Following:** Retrieve accounts that a user follows- **Multi-Platform:** Support for major social networks (Twitter/X, Instagram)- **URL Parsing:** Automatic extraction of usernames from social profile URLs- **Async Processing:** Callback support for high-volume operations- **Rate Limiting:** Built-in throttling and usage controls
## 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

- **Interaction Request:** 3 credits per successful interaction lookup
> Credits are only charged when interaction data is successfully retrieved. If no data is found, no credits are charged.
---

## POST /person/interactionsSubmit a request to fetch social interaction data.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | Type of interaction to fetch |
| `social_media_url` | string | Yes | Twitter/X or Instagram profile or post URL |
| `max_results` | integer | No | Maximum number of results to return (default: `100`) |
| `callback_url` | string | No | URL to receive results asynchronously |

> **Required:** Both type and social_media_url are required.
### Request Examples

**With Advanced Features:**

```json
{
  "type": "followers,following",
  "social_media_url": "https://twitter.com/elonmusk",
  "max_results": 100,
  "callback_url": "https://yourapp.com/webhook/interactions"
}
```

**Basic Request:**

```json
{
  "type": "replies",
  "social_media_url": "https://twitter.com/elonmusk/status/1234567890"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/interactions \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "replies",
    "social_media_url": "https://twitter.com/elonmusk/status/1234567890"
  }'
```

**Python:**

```python
import requests
import json

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

data = {
    "type": "replies",
    "social_media_url": "https://twitter.com/elonmusk/status/1234567890"
}

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

const data = {
    type: "replies",
    social_media_url: "https://twitter.com/elonmusk/status/1234567890"
};

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/interactions";
$headers = [
  "X-API-Key: YOUR_API_KEY",
  "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];

$data = [
    "type" => "replies",
    "social_media_url" => "https://twitter.com/elonmusk/status/1234567890"
];

$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 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": "interaction_abc123def456_1234567890",
    "status": "processing",
    "interaction_type": "replies",
    "platform": "twitter",
    "created_on": "2025-01-15T10:30:00Z"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

---

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

### 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": "interaction_abc123def456_1234567890",
    "status": "completed",
    "interaction_type": "followers",
    "platform": "twitter",
    "result": {
      "interaction_type": "followers",
      "source_platform": "twitter",
      "target": {
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "profile_url": "https://twitter.com/elonmusk"
      },
      "interactions": [
        {
          "username": "follower123",
          "display_name": "John Smith",
          "profile_url": "https://twitter.com/follower123",
          "bio": "Tech enthusiast",
          "followers_count": 1234,
          "following_count": 567,
          "verified": false
        }
      ],
      "total_count": 1
    },
    "result_count": 1,
    "created_on": "2025-01-15T10:30:00Z",
    "completed_on": "2025-01-15T10:31:00Z"
  },
  "timestamp": "2025-01-15T10:31:05Z"
}
```

---

## 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 status field indicates processing state: processing, completed, or failed- Interaction results include target profile information and an interactions array with matched users- Each interaction entry includes profile fields relevant to the interaction type (e.g., reply_text for replies, bio for followers)- The total_count field reflects the number of interactions returned in the result
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | Required parameters are missing (type, social_media_url, or request_id) |
| 400 | `invalid_interaction_type` | Unsupported interaction type. Valid types: replies, followers, following, followers,following (Instagram only supports "following") |
| 400 | `invalid_url` | social_media_url is not a valid URL or is from an unsupported platform. Supported: Twitter/X, Instagram |
| 400 | `invalid_callback_url` | callback_url is not a valid HTTP/HTTPS URL |
| 400 | `invalid_json` | Request body contains invalid JSON |
| 401 | `missing_credentials` | API key or secret not provided in request headers |
| 401 | `invalid_credentials` | API key or secret is incorrect or does not match |
| 401 | `api_key_expired` | API key has expired and needs to be renewed |
| 403 | `subscription_required` | Your subscription does not include access to this feature |
| 402 | `insufficient_credits` | Not enough credits remaining to process this request |
| 403 | `no_active_subscription` | No active subscription found for this API key |
| 403 | `ip_not_allowed` | Request IP address is not in this key's Allowed IPs list |
| 403 | `access_denied` | Access denied to this resource |
| 404 | `request_not_found` | Request ID not found (for GET status checks) |
| 429 | `rate_limit_exceeded` | Too many requests per minute/hour. Please slow down. |
| 429 | `monthly_limit_exceeded` | Monthly request limit exceeded. Resets at start of billing cycle. |
| 500 | `internal_error` | An unexpected server error occurred. Please try again later. |

---

## Callbacks

When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST.

### Retry Policy- Maximum 5 retry attempts- Exponential backoff: 1s, 5s, 15s, 1m, 5m- 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": "interaction_abc123def456_...",
  "status": "completed",
  "interaction_type": "followers",
  "platform": "twitter",
  "data": {
    "interaction_type": "followers",
    "source_platform": "twitter",
    "target": {
      "username": "elonmusk",
      "display_name": "Elon Musk",
      "profile_url": "https://twitter.com/elonmusk"
    },
    "interactions": [
      {
        "username": "follower123",
        "display_name": "John Smith",
        "profile_url": "https://twitter.com/follower123",
        "bio": "Tech enthusiast",
        "followers_count": 1234,
        "following_count": 567,
        "verified": false
      }
    ],
    "total_count": 50
  },
  "result_count": 50
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **Use Callbacks for Large Requests** (Recommended) — For follower/following requests that may return large datasets, always provide a callback_url to receive results asynchronously rather than polling the GET endpoint.2. **Respect Platform Limits** (Important) — Instagram only supports the "following" interaction type. Ensure your integration handles platform-specific limitations gracefully.3. **Combined Requests** (Efficient) — Use "followers,following" as the type to fetch both datasets in a single API call, reducing credit usage and latency.
---

## Note for AI Agents
When integrating with AI agents or automated systems, use the callback mechanism rather than polling the GET endpoint. This reduces unnecessary API calls and ensures timely processing of results. Implement proper error handling for platform-specific limitations (e.g., Instagram only supports "following" type).
---

## Related APIs
- **Social Newsfeed API** — Get recent posts and content → `https://api.nyne.ai/documentation/person/newsfeed`
- **Personal Interests API** — Discover personal interests → `https://api.nyne.ai/documentation/person/interests`