Instagram Engagement

curl --request GET \
  --url https://socialquery.dev/v1/instagram/engagement \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://socialquery.dev/v1/instagram/engagement', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "data": {
    "author": {
      "id": "<string>",
      "display_name": "<string>",
      "followers": 123,
      "username": "<string>",
      "avatar_url": "<string>",
      "bio": "<string>",
      "url": "<string>",
      "external_url": "<string>",
      "location": "<string>",
      "following": 123,
      "posts_count": 123,
      "likes_count": 123,
      "verified": true,
      "ext": {}
    },
    "posts": [
      {
        "post": {
          "id": "<string>",
          "url": "<string>",
          "author": {
            "id": "<string>",
            "display_name": "<string>",
            "followers": 123,
            "username": "<string>",
            "avatar_url": "<string>",
            "bio": "<string>",
            "url": "<string>",
            "external_url": "<string>",
            "location": "<string>",
            "following": 123,
            "posts_count": 123,
            "likes_count": 123,
            "verified": true,
            "ext": {}
          },
          "content": {
            "text": "<string>",
            "media_urls": [
              "<string>"
            ],
            "thumbnail_url": "<string>",
            "duration_seconds": 123
          },
          "engagement": {
            "views": 123,
            "likes": 123,
            "comments": 123,
            "shares": 123,
            "saves": 123,
            "reposts": 123
          },
          "flags": {},
          "published_at": "2023-11-07T05:31:56Z",
          "ext": {
            "platform": "<string>",
            "media_type": "image",
            "carousel_count": 123
          }
        },
        "computed": {
          "engagement_rate": 123,
          "engagement_rate_by_followers": 123,
          "likes_per_hour": 123,
          "comments_per_hour": 123
        }
      }
    ],
    "computed": {
      "avg_engagement_rate": 123,
      "avg_engagement_rate_by_followers": 123,
      "sampled_posts": 123,
      "view_rate_sample_size": 123,
      "follower_rate_sample_size": 123,
      "posting_cadence": {
        "posts_per_day": 123,
        "window_days": 123,
        "window_start": "<string>",
        "window_end": "<string>",
        "dated_posts": 123
      },
      "top_post": {
        "post": {
          "id": "<string>",
          "url": "<string>",
          "author": {
            "id": "<string>",
            "display_name": "<string>",
            "followers": 123,
            "username": "<string>",
            "avatar_url": "<string>",
            "bio": "<string>",
            "url": "<string>",
            "external_url": "<string>",
            "location": "<string>",
            "following": 123,
            "posts_count": 123,
            "likes_count": 123,
            "verified": true,
            "ext": {}
          },
          "content": {
            "text": "<string>",
            "media_urls": [
              "<string>"
            ],
            "thumbnail_url": "<string>",
            "duration_seconds": 123
          },
          "engagement": {
            "views": 123,
            "likes": 123,
            "comments": 123,
            "shares": 123,
            "saves": 123,
            "reposts": 123
          },
          "flags": {},
          "published_at": "2023-11-07T05:31:56Z",
          "ext": {
            "platform": "<string>",
            "media_type": "image",
            "carousel_count": 123
          }
        },
        "computed": {
          "engagement_rate": 123,
          "engagement_rate_by_followers": 123,
          "likes_per_hour": 123,
          "comments_per_hour": 123
        }
      },
      "format_mix": {}
    },
    "_warnings": [
      "<string>"
    ],
    "legs": [
      {
        "endpoint": "<string>",
        "status": "ok"
      }
    ],
    "followers": 123,
    "engagement_rate": 123,
    "total_likes": 123,
    "total_comments": 123,
    "sampled_posts": 123,
    "engagement_rate_unit": "ratio"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

GET

instagram

engagement

Instagram Engagement

curl --request GET \
  --url https://socialquery.dev/v1/instagram/engagement \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://socialquery.dev/v1/instagram/engagement', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "data": {
    "author": {
      "id": "<string>",
      "display_name": "<string>",
      "followers": 123,
      "username": "<string>",
      "avatar_url": "<string>",
      "bio": "<string>",
      "url": "<string>",
      "external_url": "<string>",
      "location": "<string>",
      "following": 123,
      "posts_count": 123,
      "likes_count": 123,
      "verified": true,
      "ext": {}
    },
    "posts": [
      {
        "post": {
          "id": "<string>",
          "url": "<string>",
          "author": {
            "id": "<string>",
            "display_name": "<string>",
            "followers": 123,
            "username": "<string>",
            "avatar_url": "<string>",
            "bio": "<string>",
            "url": "<string>",
            "external_url": "<string>",
            "location": "<string>",
            "following": 123,
            "posts_count": 123,
            "likes_count": 123,
            "verified": true,
            "ext": {}
          },
          "content": {
            "text": "<string>",
            "media_urls": [
              "<string>"
            ],
            "thumbnail_url": "<string>",
            "duration_seconds": 123
          },
          "engagement": {
            "views": 123,
            "likes": 123,
            "comments": 123,
            "shares": 123,
            "saves": 123,
            "reposts": 123
          },
          "flags": {},
          "published_at": "2023-11-07T05:31:56Z",
          "ext": {
            "platform": "<string>",
            "media_type": "image",
            "carousel_count": 123
          }
        },
        "computed": {
          "engagement_rate": 123,
          "engagement_rate_by_followers": 123,
          "likes_per_hour": 123,
          "comments_per_hour": 123
        }
      }
    ],
    "computed": {
      "avg_engagement_rate": 123,
      "avg_engagement_rate_by_followers": 123,
      "sampled_posts": 123,
      "view_rate_sample_size": 123,
      "follower_rate_sample_size": 123,
      "posting_cadence": {
        "posts_per_day": 123,
        "window_days": 123,
        "window_start": "<string>",
        "window_end": "<string>",
        "dated_posts": 123
      },
      "top_post": {
        "post": {
          "id": "<string>",
          "url": "<string>",
          "author": {
            "id": "<string>",
            "display_name": "<string>",
            "followers": 123,
            "username": "<string>",
            "avatar_url": "<string>",
            "bio": "<string>",
            "url": "<string>",
            "external_url": "<string>",
            "location": "<string>",
            "following": 123,
            "posts_count": 123,
            "likes_count": 123,
            "verified": true,
            "ext": {}
          },
          "content": {
            "text": "<string>",
            "media_urls": [
              "<string>"
            ],
            "thumbnail_url": "<string>",
            "duration_seconds": 123
          },
          "engagement": {
            "views": 123,
            "likes": 123,
            "comments": 123,
            "shares": 123,
            "saves": 123,
            "reposts": 123
          },
          "flags": {},
          "published_at": "2023-11-07T05:31:56Z",
          "ext": {
            "platform": "<string>",
            "media_type": "image",
            "carousel_count": 123
          }
        },
        "computed": {
          "engagement_rate": 123,
          "engagement_rate_by_followers": 123,
          "likes_per_hour": 123,
          "comments_per_hour": 123
        }
      },
      "format_mix": {}
    },
    "_warnings": [
      "<string>"
    ],
    "legs": [
      {
        "endpoint": "<string>",
        "status": "ok"
      }
    ],
    "followers": 123,
    "engagement_rate": 123,
    "total_likes": 123,
    "total_comments": 123,
    "sampled_posts": 123,
    "engagement_rate_unit": "ratio"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

Calculate engagement from one current page of public Instagram posts and the account follower count. Ratios are not percentages. Unknown counts and invalid publication times remain null. A successful uncached call costs 5 credits. Engagement requires both profile and posts; if either is unavailable, the request fails and is refunded. Rates are decimal ratios: 0.05 means 5%. The view-based rate uses (likes + comments + available shares) / views; absent shares remain null in the post and are excluded from the numerator. The follower-based rate uses (likes + comments) / followers. Each average includes only eligible sampled posts. Facebook likes represent total source reactions. Photo-only Instagram posts have no view count. Cadence is (dated posts - 1) / days between the oldest and newest sampled posts, including pinned posts. The measured window and dated sample size are returned. Missing and future timestamps are excluded; velocity is cumulative likes/comments divided by post age, not a measured hourly change. The top post is ranked by follower-based engagement within this page. Unknown lifetime post counts stay null.

Authorizations

x-api-key

string

header

required

Headers

Cache-Control

string

Idempotency-Key

string

X-Max-Credits

integer

Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero.

Required range: x >= 0

Query Parameters

handle

string

required

Public username, optionally prefixed with @.

Response

Calculate engagement from one current page of public Instagram posts and the account follower count. Ratios are not percentages. Unknown counts and invalid publication times remain null.

success

boolean

required

platform

string

required

endpoint

string

required

credits_used

integer

required

Required range: x >= 0

credits_remaining

integer | null

required

request_id

string

required

cached

boolean

required

data

object

required

The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null.

Show child attributes