Nyne Nyne API Login
Person APIs

Social Interactions

Network-intelligence lookup that maps the people a target interacts with on Twitter/X or Instagram (repliers, followers, following). The platform is inferred from social_media_url; Twitter/X supports replies, followers, following (and the compound followers,following), while Instagram supports followers, following, and followers,following. The request is queued and returns a request_id to poll; for large requests prefer a callback_url, which receives the completed result. Returned fields vary by interaction type - replies carry reply_text/reply_date, follower/following entries carry profile fields like bio, followers_count, following_count, and verified.

POST https://api.nyne.ai/person/interactions API key

Manual credentials take precedence over your account key.

Try it needs these required parameters:

Overview

Surface a person’s social interactions and engagement.

Parameters

social_media_url string required
Twitter/X or Instagram profile or status URL. The platform, username, and tweet id are inferred from it. Aliased as twitter_url.
type string required
Interaction type (aliased as interaction_type). Twitter/X: replies · followers · following · followers,following. Instagram: followers · following · followers,following.
username string optional
Handle (leading @ stripped). Required for follower/following lookups and all Instagram lookups when no URL is given.
tweet_id string optional
Tweet id for replies on Twitter/X (10-25 digits). Extracted from a /status/ URL when present.
max_results integer optional
Result cap. Default 100, clamped to 10-1000.
callback_url string optional
If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured.

Retrieving the result

This endpoint is asynchronous. A successful submit returns a request_id while the job runs in the background. Poll the same path with a GET request - same authentication headers - passing the request_id as a query parameter:

Loading your API credentials...

Each poll returns the job's current status; once it is completed the payload carries the result shown under Responses. Polling an unknown or expired request_id returns 404 request_not_found.

Status Meaning
queued · processing · pending The job is still running - keep polling.
completed The job finished; the payload carries the result and completed: true.
failed Terminal - the job could not complete; the error field explains why.

Poll every few seconds at first, backing off for long-running jobs. Polling is free - status checks never burn credits.

Prefer push delivery?
Supply the optional callback_url parameter and the completed payload is POSTed to your endpoint when the job finishes - no polling required. Delivery is retried up to 5 times with exponential backoff (1s, 5s, 15s, 1m, 5m) and a 30-second timeout per attempt; respond with a 2xx status to acknowledge receipt.

Credit usage

Credits are charged based on the matched configuration. The listed cost is the per-result unit price.

Feature Credits Notes
Network Intelligence Request 3 Charged per request
No results 0 Empty results never burn credits
Heads up
A positive credit balance is required before each request. Empty results do not burn credits.

Responses

200 Status poll result - returns the current request status and result/error fields when available
202 Request queued - poll the status endpoint (or wait for the callback) with the returned request_id
400 Malformed JSON, missing required parameters, or an invalid field
401 Missing or invalid API credentials
402 insufficient_credits - not enough credits to complete the request
403 subscription_required or ip_not_allowed
404 request_not_found - no matching request is available for this API key
429 rate_limit_exceeded
503 service_unavailable - the API is temporarily unavailable

A successful response wraps the payload in the { success, data, timestamp } envelope (also shown live in the panel on the right):

{
  "success": true,
  "data": {
    "request_id": "interaction_a1b2c3d4e5f6a1b2_1717000000_4271",
    "status": "completed",
    "completed": true,
    "result": {
      "interaction_type": "followers",
      "platform": "twitter",
      "target": {
        "username": "janedoe",
        "profile_url": "https://x.com/janedoe"
      },
      "interactions": [
        {
          "username": "john_smith",
          "display_name": "John Smith",
          "profile_url": "https://x.com/john_smith",
          "followers_count": 2134,
          "verified": false
        },
        {
          "username": "alice_j",
          "display_name": "Alice Johnson",
          "profile_url": "https://x.com/alice_j",
          "followers_count": 5678,
          "verified": true
        }
      ],
      "total_count": 2
    },
    "completed_on": "2026-01-15T10:31:00Z"
  },
  "timestamp": "2026-01-01T00:00:00"
}