Search Instagram users

POST/v1/tools/instagram.search.users/callsNeeds an API key

Returns the Instagram accounts that match a search, with name and picture. Use it to find an account and get the user ID that instagram.user.posts takes.

Tool instagram.search.users on Instagram. Contract version 1, released 2026-11-01.

Over REST, send the input in the body. Over MCP, pass the same input to call_tool.

Both return the full response: the call's ID, status and cost, with this tool's result in output.

Input

querystringRequired

The search query, matched against handles and display names.

Output

A successful call returns these blocks in its output. A field not marked required can be null.

`users`

A list of rows. Always present, possibly empty.

idstringRequired

Instagram's numeric identifier of the user, as a string, which instagram.user.posts takes as user_id.

usernamestring

The user's handle, without the @. The profile is at https://www.instagram.com/ followed by it.

namestring

The user's display name.

image_urlstring

Address of the user's profile picture. Instagram's media addresses expire.

verifiedboolean

Whether Instagram marks the user as verified.

privateboolean

Whether the account is private, its posts shown only to approved followers.

approx_follower_countinteger

Number of followers, approximate, rounded by the source (22.9M is 22900000).

curl https://api.voxoria.ai/v1/tools/instagram.search.users/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"coffee"}}'

import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/instagram.search.users/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={"input": {"query": "coffee"}},
    timeout=60,
)
print(response.json())

const response = await fetch("https://api.voxoria.ai/v1/tools/instagram.search.users/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"input": {"query": "coffee"}}),
});
console.log(await response.json());

{
  "name": "call_tool",
  "arguments": {
    "tool": "instagram.search.users",
    "input": {
      "query": "coffee"
    }
  }
}

200 OKoutputapplication/json

{
  "users": [
    {
      "id": "76611403262",
      "username": "guangzhou_alis",
      "name": "Alis coffee shop",
      "image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-19/836547548_17908619214555263_5845838767090705551_n.jpg?stp=dst-jpg_e0_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDgwLmMyIn0&_nc_ht=instagram.fbcn2-1.fna.fbcdn.net&_nc_cat=111&_nc_oc=Q6cZ2gGks9e_4ccLmpOR9uRxrdVwMR5wwIXaZXmPXgINrqIvMkGxWaNZsPTNQi6BqOXE2go&_nc_ohc=o9AIwSJLUCUQ7kNvwEvmMcI&_nc_gid=RWyvmynO7Z6HBOCyIg_agQ&edm=ALgmGsQBAAAA&ccb=7-5&ig_cache_key=GNyz3DF-iLNWy58-AI8kptZilyBRbmNDAQAB1501500j-ccb7-5&oh=00_AQRpw_aoSwU44UgiUjNVy2iu5G3_awEhXM48X9BzDPNF3w&oe=6AECD8C2&_nc_sid=2f557e",
      "verified": false,
      "private": false,
      "approx_follower_count": null
    },
    {
      "id": "40714747532",
      "username": "coffeesiamese",
      "name": "Coffee",
      "image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-19/773589697_18079345334355533_1083067560581283414_n.jpg?stp=dst-jpg_e0_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4zMjAuYzIifQ&_nc_ht=instagram.fbcn2-1.fna.fbcdn.net&_nc_cat=105&_nc_oc=Q6cZ2gGks9e_4ccLmpOR9uRxrdVwMR5wwIXaZXmPXgINrqIvMkGxWaNZsPTNQi6BqOXE2go&_nc_ohc=dNm1wqZ1HNAQ7kNvwHWQKHg&_nc_gid=RWyvmynO7Z6HBOCyIg_agQ&edm=ALgmGsQBAAAA&ccb=7-5&ig_cache_key=GMEKHC5NBm2cETtAAFY_MkA11AcPbmNDAQAB1501500j-ccb7-5&oh=00_AQRmGWqOHRIlqo7U4Ap4HVWgdIU1YwomTGt57LcDRKzEvQ&oe=6AECA432&_nc_sid=2f557e",
      "verified": false,
      "private": false,
      "approx_follower_count": null
    },
    {
      "id": "46014483887",
      "username": "coffee.a.m",
      "name": "𝒜🫶🏻",
      "image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-19/687310298_18083480318531888_2186725987714030235_n.jpg?stp=dst-jpg_e0_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDgwLmMyIn0&_nc_ht=instagram.fbcn2-1.fna.fbcdn.net&_nc_cat=108&_nc_oc=Q6cZ2gGks9e_4ccLmpOR9uRxrdVwMR5wwIXaZXmPXgINrqIvMkGxWaNZsPTNQi6BqOXE2go&_nc_ohc=FhnfPKqghREQ7kNvwGu8-Ww&_nc_gid=RWyvmynO7Z6HBOCyIg_agQ&edm=ALgmGsQBAAAA&ccb=7-5&ig_cache_key=GNqF9ygwWbBc1D5AAJtazzazz1gebmNDAQAB1501500j-ccb7-5&oh=00_AQR-KvzYsUndD2qXHJWbgsF_7NVqC4ZR5611HxQO8glSaw&oe=6AECA2CE&_nc_sid=2f557e",
      "verified": false,
      "private": false,
      "approx_follower_count": null
    }
  ]
}

The output of a real call, each list cut to 3 items.