Instagram Tagged Posts API

curl --request POST \
  --url https://api.socq.ai/v1/instagram/tagged-posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "usernames": [
    "<string>"
  ],
  "results_limit": 1000
}
'

import requests

url = "https://api.socq.ai/v1/instagram/tagged-posts"

payload = {
    "usernames": ["<string>"],
    "results_limit": 1000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({usernames: ['<string>'], results_limit: 1000})
};

fetch('https://api.socq.ai/v1/instagram/tagged-posts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.socq.ai/v1/instagram/tagged-posts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'usernames' => [
        '<string>'
    ],
    'results_limit' => 1000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.socq.ai/v1/instagram/tagged-posts"

	payload := strings.NewReader("{\n  \"usernames\": [\n    \"<string>\"\n  ],\n  \"results_limit\": 1000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.socq.ai/v1/instagram/tagged-posts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"usernames\": [\n    \"<string>\"\n  ],\n  \"results_limit\": 1000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.socq.ai/v1/instagram/tagged-posts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"usernames\": [\n    \"<string>\"\n  ],\n  \"results_limit\": 1000\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "data": {
    "task_id": "<string>",
    "status": "<string>",
    "created_time": "<string>"
  }
}

{
  "code": 422,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "details": {}
  }
}

POST

instagram

tagged-posts

Instagram Tagged Posts API

curl --request POST \
  --url https://api.socq.ai/v1/instagram/tagged-posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "usernames": [
    "<string>"
  ],
  "results_limit": 1000
}
'

import requests

url = "https://api.socq.ai/v1/instagram/tagged-posts"

payload = {
    "usernames": ["<string>"],
    "results_limit": 1000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({usernames: ['<string>'], results_limit: 1000})
};

fetch('https://api.socq.ai/v1/instagram/tagged-posts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.socq.ai/v1/instagram/tagged-posts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'usernames' => [
        '<string>'
    ],
    'results_limit' => 1000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.socq.ai/v1/instagram/tagged-posts"

	payload := strings.NewReader("{\n  \"usernames\": [\n    \"<string>\"\n  ],\n  \"results_limit\": 1000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.socq.ai/v1/instagram/tagged-posts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"usernames\": [\n    \"<string>\"\n  ],\n  \"results_limit\": 1000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.socq.ai/v1/instagram/tagged-posts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"usernames\": [\n    \"<string>\"\n  ],\n  \"results_limit\": 1000\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "data": {
    "task_id": "<string>",
    "status": "<string>",
    "created_time": "<string>"
  }
}

{
  "code": 422,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "details": {}
  }
}

Instagram Tagged Posts

{"usernames": ["instagram"], "results_limit": 20}

Use with MCP

Interface	Value
REST	`POST /v1/instagram/tagged-posts`
Compact MCP	`socq_execute` with `endpoint: "instagram/tagged-posts"`
Typed MCP	`socq_instagram_tagged_posts`
CLI	`socq instagram tagged-posts`

Results use the normalized Instagram post shape and include available tags, mentions, media, and engagement metrics.

Result Fields

Task results use the stable SocQ fields below. Source-specific field names and formats are normalized without inferring or enriching values that the source did not provide. To request a smaller field set, use fields for MCP queries, _result_fields for typed tools, or --result-fields in the CLI. Declared fields remain present when their value is null.

Field	Type	Nullable	Description
`id`	`string`	Yes	Unique identifier for this result item.
`platform`	`string`	No	Platform the result belongs to, such as `instagram` or `linkedin`.
`resource`	`string`	No	SocQ resource represented by the result, such as `videos` or `comments`.
`type`	`string`	No	Category of the result item, such as `video`, `post`, or `comment`.
`url`	`string`	Yes	Public URL of the result item when available.
`published_at`	`string`	Yes	Time the source item was published, in ISO 8601 format when available.
`collected_at`	`string`	No	Time SocQ collected or processed this result, in ISO 8601 format.
`text`	`string`	Yes	Post body, caption, or message.
`author`	`object`	Yes	Author or publisher of the content.
`author.id`	`string`	Yes	Unique identifier of the author.
`author.username`	`string`	Yes	Public username or handle of the account.
`author.name`	`string`	Yes	Display name of the author.
`author.url`	`string`	Yes	Public URL of the author when available.
`author.avatar_url`	`string`	Yes	URL of the account avatar image.
`author.is_verified`	`boolean`	Yes	Whether the account is verified on the platform.
`author.is_private`	`boolean`	Yes	Whether the account is private.
`metrics`	`object`	Yes	Counters and measurements available for the result item.
`metrics.likes_count`	`integer`	Yes	Number of likes.
`metrics.comments_count`	`integer`	Yes	Number of comments.
`metrics.shares_count`	`integer`	Yes	Number of shares or reposts.
`metrics.views_count`	`integer`	Yes	Number of views reported by the platform.
`media`	`array<object>`	Yes	Images, videos, or other media attached to the result.
`media.type`	`string`	Yes	Media kind, such as `image` or `video`.
`media.url`	`string`	Yes	URL of the media asset.
`media.thumbnail_url`	`string`	Yes	URL of the media preview image.
`media.width`	`integer`	Yes	Media width in pixels.
`media.height`	`integer`	Yes	Media height in pixels.
`media.duration_seconds`	`number`	Yes	Media duration in seconds.
`hashtags`	`array<string>`	Yes	Hashtags associated with the content, without changing their source spelling.
`mentions`	`array<string>`	Yes	Accounts mentioned in the content.

Completed Task Response

{
  "code": 200,
  "data": {
    "task_id": "G5L9ZSVUSLKGMIL2",
    "status": "succeeded",
    "public_id": "instagram/tagged-posts",
    "result_count": 5,
    "credits_amount": 2.5,
    "results": {
      "limit": 1,
      "next_cursor": "NjUzNQ",
      "has_more": true,
      "schema_id": "post",
      "schema_version": "1.0",
      "items": [
        {
          "id": "2251138696266127152",
          "platform": "instagram",
          "resource": "tagged-posts",
          "type": "post",
          "url": "https://www.instagram.com/p/B89prebFBcw/",
          "published_at": "2020-02-24T20:37:46Z",
          "collected_at": "2026-07-31T02:23:32.685890Z",
          "text": "Uma homenagem a rede social que contribui muito para divulgação do meu trabalho.\n.\nO Instagram tem sido para mim muito mais que uma simples rede social; essa plataforma que além de criar uma conexão com pessoas que queremos por perto, tem ajudado assim como eu  milhões de pessoas a divulgar o seu negócio.\nEssa poderosa Midia social, gerou milhares de empregos, e continua dando a oportunidade para todos os que desejam divulgar o que fazem de melhor.\n.\n.\n\nA tribute to the social network that contributes a lot to spread my work. . For me, Instagram has been much more than just a social network; this platform that in addition to creating a connection with people we want close by, has helped millions of people to publicize their business just like me. This powerful social media has created thousands of jobs, and continues to provide an opportunity for everyone who wants to spread the word about what they do best. .\nTHANK YOU @instagram!",
          "author": {
            "id": "3021079942",
            "username": "lucasramosmendes",
            "name": "LUCAS RAMOS MENDES ®",
            "url": "https://www.instagram.com/lucasramosmendes/",
            "avatar_url": null,
            "is_verified": null,
            "is_private": null
          },
          "metrics": {
            "likes_count": 149853,
            "comments_count": 10253,
            "shares_count": null,
            "views_count": null
          },
          "media": [
            {
              "type": "image",
              "url": "https://scontent-iev1-1.cdninstagram.com/v/t51.82787-15/621585839_18092087866989349_3372003390585135619_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=103&ig_cache_key=MjI1MTEzODY5NjI2NjEyNzE1Mg%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6IkZFRUQueHBpZHMuMTQ0MC5zZHIucmVndWxhcl9waG90by5DMyJ9&_nc_ohc=CH-XViRL-3MQ7kNvwE_hxY3&_nc_oc=AdqllXfBCRo7CL60skDMRd--PFUL-0CQy3TmWTAQGbyKM7m4GE9px64T8ZvXZjpBjbM&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&se=8&_nc_ht=scontent-iev1-1.cdninstagram.com&_nc_gid=vDc_3BFhiq8MKoXQEqV17w&_nc_ss=7a3ba&oh=00_AQHh8WwSqzL7n7pHJRLFROY5WkQVamXQZ6sUUklRL6lnzA&oe=6A71E37C",
              "thumbnail_url": "https://scontent-iev1-1.cdninstagram.com/v/t51.82787-15/621585839_18092087866989349_3372003390585135619_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=103&ig_cache_key=MjI1MTEzODY5NjI2NjEyNzE1Mg%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6IkZFRUQueHBpZHMuMTQ0MC5zZHIucmVndWxhcl9waG90by5DMyJ9&_nc_ohc=CH-XViRL-3MQ7kNvwE_hxY3&_nc_oc=AdqllXfBCRo7CL60skDMRd--PFUL-0CQy3TmWTAQGbyKM7m4GE9px64T8ZvXZjpBjbM&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&se=8&_nc_ht=scontent-iev1-1.cdninstagram.com&_nc_gid=vDc_3BFhiq8MKoXQEqV17w&_nc_ss=7a3ba&oh=00_AQHh8WwSqzL7n7pHJRLFROY5WkQVamXQZ6sUUklRL6lnzA&oe=6A71E37C",
              "width": 1440,
              "height": 1800,
              "duration_seconds": null
            }
          ],
          "hashtags": [],
          "mentions": [
            "instagram"
          ]
        }
      ]
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

usernames

string[]

required

Public account usernames.

Minimum array length: 1

Minimum string length: 1

results_limit

integer

Required range: 1 <= x <= 2000

Response

Task accepted

code

integer

data

object

Show child attributes

Overview

Instagram

Facebook

Facebook Marketplace

Facebook Ad Library

Google Ad Library

YouTube

TikTok

TikTok Ad Library

TikTok Shop

X

LinkedIn

LinkedIn Ad Library

Reddit

Pinterest

Threads

Snapchat

Twitch

Bluesky

Kwai

Truth Social

Google Maps

Amazon

Google Play

Apple App Store

Rednote

Douyin

SEO

Common

Instagram Tagged Posts

Instagram Tagged Posts

Use with MCP

Result Fields

Completed Task Response

Authorizations

Body

Response

​Instagram Tagged Posts

​Use with MCP

​Result Fields

​Completed Task Response

Authorizations

Body

Response

Instagram Tagged Posts

Use with MCP

Result Fields

Completed Task Response