# Search Instagram users

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.

## Example call

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

cURL:

```bash
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"}}'
```

Python:

```python
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())
```

TypeScript:

```ts
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());
```

MCP (`tools/call` params):

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

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | Yes |  | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Instagram's numeric identifier of the user, as a string, which instagram.user.posts takes as user_id. |
| `username` | string | No | The user's handle, without the @. The profile is at https://www.instagram.com/ followed by it. |
| `name` | string | No | The user's display name. |
| `image_url` | string | No | Address of the user's profile picture. Instagram's media addresses expire. |
| `verified` | boolean | No | Whether Instagram marks the user as verified. |
| `private` | boolean | No | Whether the account is private, its posts shown only to approved followers. |
| `approx_follower_count` | integer | No | Number of followers, approximate, rounded by the source (22.9M is 22900000). |

## Example output

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

```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
    }
  ]
}
```