Overview

The Person Interactions API allows you to fetch social interaction data from Twitter/X and Instagram profiles. This includes people who replied to specific tweets, account followers, and accounts a user follows.

Authentication

All API requests require authentication using your API key and secret. You can authenticate using either HTTP headers (recommended) or query parameters.

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

Rate Limits

API usage is controlled by rate limiting mechanisms to ensure fair usage and system stability:

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

Credit Usage

API credits are consumed based on the interaction request:

• Interaction Request: 3 credits per successful interaction lookup

POST /person/interactions

Submit a request to fetch social interaction data.

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

import requests
import json

url = "https://api.nyne.ai/person/interactions"
headers = {
    "X-API-Key": "your_api_key_here",
    "X-API-Secret": "your_api_secret_here",
    "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))

const url = "https://api.nyne.ai/person/interactions";
const headers = {
    "X-API-Key": "your_api_key_here",
    "X-API-Secret": "your_api_secret_here",
    "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
$url = "https://api.nyne.ai/person/interactions";
$headers = [
    "X-API-Key: your_api_key_here",
    "X-API-Secret: your_api_secret_here",
    "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);
?>

GET /person/interactions

Check the status of an interaction request and retrieve results.

Interaction Type: Replies

Fetch users who replied to a specific tweet.

Example Request

Response Fields

• username: Twitter handle of the replier
• display_name: Display name
• reply_text: Content of the reply
• reply_date: When the reply was posted
• likes_count: Number of likes on the reply
• retweets_count: Number of retweets

Interaction Type: Followers

Fetch users who follow a specific account.

Example Request

Response Fields

• username: Twitter handle of the follower
• display_name: Display name
• bio: User biography
• followers_count: Their follower count
• following_count: How many they follow
• verified: Verification status

Interaction Type: Following

Fetch accounts that a specific user follows.

Example Request

Usage Statistics

Usage statistics are available through the unified usage API at /usage. This endpoint provides comprehensive usage information including credits used, monthly allocation, and breakdown by API type.

Response Format

All API responses follow a consistent JSON format:

Success Response

Error Response

Error Codes

The API returns structured error responses with specific error codes to help you handle issues programmatically.

Authentication Errors (401)

Validation Errors (400)

Authorization Errors (403)

Not Found Errors (404)

Rate Limit Errors (429)

Server Errors (500)

Error Response Example

Callback System

When you provide a callback_url, the API will send the interaction results to your endpoint via HTTP POST when processing is complete.

Callback Request Format

Callback 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

Callback Error Format

Important: Your callback endpoint should respond with HTTP 200-299 to indicate successful receipt. Any other response code will trigger a retry.