Search accounts

POST /v1/instagram/accounts/search finds whole accounts. Send one account block with a semantic query about who the account is and structural filters. Add an optional posts scope that qualifies accounts through their publishing. This page is the whole endpoint: identity queries, filtering, the posts scope, ordering, and how to read what comes back.

To find content rather than people, use Search posts; it returns individual posts. A common workflow: discover content there, qualify its authors here.

Query the identity

account.query describes who you’re looking for, for example "sporty stay-at-home moms". Klint qualifies each account against its current observed identity: the public profile plus recurring or representative published content.

curl
Python
TypeScript

curl -X POST "https://api.tryklint.ai/v1/instagram/accounts/search" \
  -H "Authorization: Bearer $KLINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "account": {
    "query": "sporty stay-at-home moms",
    "filters": {
      "followers_count": {
        "gte": 5000,
        "lte": 50000
      }
    },
    "posts": {
      "minimum_matching_posts": 3,
      "filters": {
        "posted_at": {
          "gte": "2026-04-01T00:00:00Z",
          "lt": "2026-07-01T00:00:00Z"
        }
      }
    }
  },
  "limit": 10
}'

import os, requests

resp = requests.post(
    "https://api.tryklint.ai/v1/instagram/accounts/search",
    headers={"Authorization": f"Bearer {os.environ['KLINT_API_KEY']}"},
    json={
  "account": {
    "query": "sporty stay-at-home moms",
    "filters": {
      "followers_count": {
        "gte": 5000,
        "lte": 50000
      }
    },
    "posts": {
      "minimum_matching_posts": 3,
      "filters": {
        "posted_at": {
          "gte": "2026-04-01T00:00:00Z",
          "lt": "2026-07-01T00:00:00Z"
        }
      }
    }
  },
  "limit": 10
},
)
results = resp.json()

const resp = await fetch("https://api.tryklint.ai/v1/instagram/accounts/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KLINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "account": {
      "query": "sporty stay-at-home moms",
      "filters": {
        "followers_count": {
          "gte": 5000,
          "lte": 50000
        }
      },
      "posts": {
        "minimum_matching_posts": 3,
        "filters": {
          "posted_at": {
            "gte": "2026-04-01T00:00:00Z",
            "lt": "2026-07-01T00:00:00Z"
          }
        }
      }
    },
    "limit": 10
  }),
});
const results = await resp.json();

Full response

{
  "request_id": "req_example_03",
  "data": [
    {
      "id": "ig_account_01j2k9m4q7",
      "handle": "mayamoveswell",
      "display_name": "Maya | Family Wellness",
      "web_url": "https://www.instagram.com/mayamoveswell/",
      "avatar_url": "https://media.tryklint.ai/accounts/ig_account_01j2k9m4q7/avatar",
      "biography": "Sporty stay-at-home mom sharing practical kids gut-health and family-wellness tips. Spokane, WA.",
      "bio_links": [
        {
          "url": "https://mayamoveswell.example/resources",
          "title": "Free family wellness guides"
        }
      ],
      "account_type": "creator",
      "category_label": "Health/beauty",
      "declared_locations": [
        {
          "country_code": "US",
          "region_code": "US-WA",
          "locality": "Spokane"
        }
      ],
      "is_verified": false,
      "is_private": false,
      "followers_count": 24300,
      "following_count": 684,
      "posts_count": 418,
      "publishing_summary": "Shares practical family-wellness education through at-home fitness routines, simple meal preparation, and recurring explanations of children's gut health.",
      "publishing_languages": [
        "en"
      ],
      "niches": [
        "family_wellness",
        "gut_health",
        "home_fitness"
      ],
      "observed_at": "2026-07-15T15:40:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

These rules decide who comes back:

Every material trait must qualify. For “sporty stay-at-home moms,” an account must qualify as sporty and as a stay-at-home mom. Strength on one trait never compensates for absence of another.
One direct self-description is enough for what it states. A biography saying “stay-at-home mom” establishes that trait without repetition.
Behavioral traits need recurrence. An account is “sporty” through recurring fitness content, not one gym post. A single incidental post never redefines an account.
Evidence can live anywhere. Relationship language in a caption (“my kids”) counts like biography text. You don’t predict where an account disclosed something; Klint looks across profile and content.
Current contradictions block; missing history doesn’t. Klint qualifies against what it observed. Known current evidence that contradicts a trait prevents qualification; incomplete coverage alone doesn’t.

Writing a query that qualifies

Identity queries are stricter than content queries: every material trait must independently qualify. Ask for the one or two traits your workflow actually needs.

Query	What must be true
`"sporty stay-at-home moms"`	Recurring fitness/active content (behavioral) and affirmative stay-at-home-mom evidence (stated in profile or authored content)
`"veterinarians who post grooming tutorials"`	Affirmative evidence of being a veterinarian; recurring vet-adjacent content alone establishes a topic, not a profession
`"micro creators in Spokane"`	Don’t. Put size in `followers_count` and place in `declared_locations` filters; keep the query for identity that needs interpretation

Two habits improve results:

Move hard constraints into filters. Follower ranges, languages, account type, and locations are exact, so filters on them are exact.
Don’t stack rare traits casually. "left-handed vegan triathlete dads" mostly proves that what Klint has observed can’t evidence four independent traits at once.

Filter the accounts

Filters are hard constraints: Klint returns an account only if it satisfies every filter. Every filter value is an operator object; there is no bare-value shorthand. "account_type": "creator" is rejected; "account_type": { "in": ["creator"] } is correct.

Operators

Operator	Applies to	Meaning	Example
`in`	singular fields	The field’s one value is any of the supplied alternatives	`"account_type": { "in": ["creator", "business"] }`
`contains_any`	collection fields	The collection contains at least one supplied value	`"niches": { "contains_any": ["pets"] }`
`contains_all`	collection fields	The collection contains every supplied value	`"publishing_languages": { "contains_all": ["en", "es"] }`
`gt` / `gte` / `lt` / `lte`	ordered scalars	The value satisfies the numeric bounds	`"followers_count": { "gte": 10000, "lte": 50000 }`
direct boolean	boolean fields	The observed value equals the supplied boolean	`"is_verified": true`

Rules that follow from the shapes:

A field takes exactly one operator. contains_any and contains_all never combine on the same field.
Membership arrays are non-empty and hold unique values.
Ranges need at least one bound and allow at most one lower and one upper bound. Klint rejects contradictory bounds.

Different fields AND together. No cross-field OR, no negation, no missing-value operator, no expression language. The grammar is deliberately closed and positive-only.

null never matches. A missing or hidden value satisfies no filter: no range, no membership, no boolean in either direction. “Unknown” is not expressible in the launch grammar.

Values normalize the same way as post filters: languages use BCP 47 tags with basic range matching ("en" matches en-US), and classification IDs (niches) are exact catalog IDs, never display labels. Klint rejects an unrecognized ID with suggestions rather than fuzzy-resolving it.

Account filter fields

Field	Shape	Matches when
`id`	`in`	The account’s Klint ID is one of the supplied IDs
`handle`	`in`	The current bare handle is one of the supplied handles
`followers_count`	range	The current observed follower count is within bounds
`is_verified`	boolean	Verification state was observed and equals the value
`account_type`	`in`	The directly established type is one of `personal`, `creator`, `business`
`declared_locations`	`contains_any`	One declared location matches every component of one supplied alternative
`publishing_languages`	`contains_any` / `contains_all`	The account’s publishing languages contain any / all requested tags
`niches`	`contains_any` / `contains_all`	The account’s niches contain any / all requested IDs

Each declared_locations alternative is an object with a required country_code (ISO 3166-1) and optional region_code and locality. All supplied components must match the same declared location. You cannot combine one location’s country with another’s city.

Locality matching may launch restricted to ISO country and region codes, with locality as response context only. Canonical normalization (St. Louis vs Saint Louis) is unresolved design.

Not filterable at launch: following_count, posts_count, category_label, biography text, privacy state (Klint never returns private accounts), growth, or any audience/demographic inference.

The posts scope

account.posts qualifies accounts through their publishing: minimum_matching_posts sets how many distinct posts must each satisfy the complete account.posts.filters predicate. Those filters use the post filter fields.

{
  "account": {
    "filters": {
      "followers_count": {
        "gte": 5000,
        "lte": 50000
      },
      "niches": {
        "contains_any": ["pets"]
      }
    },
    "posts": {
      "minimum_matching_posts": 1,
      "filters": {
        "posted_at": {
          "gte": "2026-05-01T00:00:00Z",
          "lt": "2026-07-01T00:00:00Z"
        },
        "views": {
          "gte": 200000
        }
      }
    }
  },
  "sort": {
    "by": "followers_count",
    "order": "desc"
  },
  "limit": 10
}

Full response

{
  "request_id": "req_example_04",
  "data": [
    {
      "id": "ig_account_2j1x",
      "handle": "dogmomdaily",
      "display_name": "Dog Mom Daily",
      "web_url": "https://www.instagram.com/dogmomdaily/",
      "avatar_url": "https://media.tryklint.ai/accounts/ig_account_2j1x/avatar",
      "biography": "Golden retriever mom sharing real-life grooming and shedding hacks 🐾",
      "bio_links": [
        {
          "url": "https://dogmomdaily.example/favorites",
          "title": "Our favorite grooming tools"
        }
      ],
      "account_type": "creator",
      "category_label": "Blogger",
      "declared_locations": [],
      "is_verified": false,
      "is_private": false,
      "followers_count": 21400,
      "following_count": 512,
      "posts_count": 267,
      "publishing_summary": "Documents at-home dog care through grooming-product demonstrations, shedding-management routines, and day-in-the-life content with a golden retriever.",
      "publishing_languages": [
        "en"
      ],
      "niches": [
        "pets",
        "dog_care"
      ],
      "observed_at": "2026-07-15T09:20:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Rules worth internalizing:

The whole predicate must hold on one post. An account with one post carrying the right hashtags and a different post clearing the views bar does not qualify; facts from different posts never combine.
A carousel counts once, no matter how many media items it contains.
The default minimum is 1; the provisional launch maximum is 3.

Whether account.posts counts only posts the account authored, or also posts where it accepted Instagram Collab coauthorship, is an open contract decision.

What gets rejected

A non-matching filter is a valid request that returns data: []. An invalid filter never executes; it returns a 422 validation-failed problem object that names the exact pointer, reason, and correction. The clearest case is a classification ID that isn’t in the catalog. Klint never fuzzy-resolves it to a nearby ID and never lets it evaluate silently to an empty result. It rejects with reason INVALID and, when close IDs exist, a candidates list to correct from:

{ "account": { "filters": { "niches": { "contains_any": ["dog_grooming_deluxe"] } } } }

{
  "type": "https://api.tryklint.ai/problems/validation-failed",
  "status": 422,
  "request_id": "req_example_47",
  "detail": "One request field needs correction.",
  "errors": [
    {
      "pointer": "#/account/filters/niches/contains_any/0",
      "reason": "INVALID",
      "detail": "Unknown niche ID 'dog_grooming_deluxe'. Classification values are exact catalog IDs.",
      "candidates": [
        {
          "id": "dog_care",
          "label": "Dog care"
        },
        {
          "id": "pets",
          "label": "Pets"
        }
      ]
    }
  ]
}

The same grammar rejects, with 422 validation-failed:

Bare values: "account_type": "creator" instead of { "in": ["creator"] } (reason INVALID).
Unknown fields: following_count or category_label are not filterable keys (reason UNKNOWN).
Contradictory ranges: "followers_count": { "gte": 50000, "lte": 10000 } (reason INVALID).
Negation attempts: there is no not_in, exclude, or none (reason UNKNOWN).

Search posts shows each of these with its full response body.

Ordering and pagination

Ordering

A query-bearing search returns relevance order; Klint rejects sort sent with a query (422). A filters-only account search accepts an optional sort object, { "by": "followers_count", "order": "desc" }, over a closed list of stable scalar fields. A stable resource ID is the final tie-breaker. Ranking a relevance window by a metric would misrepresent a retrieval window as the whole of Instagram. Metric ordering therefore requires a structural (filters-only) population whose eligibility is exact.

Pagination

An initial search pins an immutable result sequence: Klint freezes the request, a snapshot of what it tracks, and the ranking together. Each response returns one page plus an opaque cursor. Continuation sends only that cursor plus an optional same-or-lower limit. The rules:

The sequence never recomputes. An account whose identity changes after your search never shifts mid-pagination. Run a new search to see newer state.
has_more speaks about the pinned session, not about whether Instagram holds other matches.
Pages can run short. Klint suppresses, rather than backfills, an account that goes private after the snapshot.
Cursors expire. After a short lifetime, continuation returns 410 expired-cursor rather than recomputing against live data:

{
  "type": "https://api.tryklint.ai/problems/expired-cursor",
  "status": 410,
  "request_id": "req_example_52",
  "detail": "This cursor's pinned search session has ended. Start a new search to see current results."
}

Provisional page bounds: default 20, maximum 100 per page.

Reading the results

Search and Get account return the identical full account representation; there is no reduced “search card.” A few semantics keep it trustworthy:

id is durable; handle is not. The id survives handle changes, display-name changes, and profile rewrites. Never key on handle.
Two kinds of truth on one object. Current profile facts (biography, account_type, category_label, declared_locations, is_verified, counters) come from what Instagram displays now. Publishing interpretation (publishing_summary, publishing_languages, niches) comes from a bounded set of recent posts. They have different sources and different freshness; don’t cross-read them. category_label (Instagram’s self-presentation text) and niches (Klint catalog IDs) routinely disagree, and neither derives from the other.
declared_locations is declared, never inferred. Klint never reads it from geotags, travel content, or audience. [] means a complete check found no declared base.
Zero is real. following_count: 0 is an observed count; unavailable counts are null.
Private accounts leave search. Search never returns a confirmed-private account; GET may still show its public profile facts with every publishing field cleared to null.

Posts embed their author as a fixed seven-field summary (id, handle, display_name, web_url, avatar_url, followers_count, is_verified). It’s relationship context, not analytical evidence. Dereference id with Get account when freshness or the fuller picture matters.

Get Started

Instagram

Cookbooks

For Agents

Search accounts

Query the identity

Writing a query that qualifies

Filter the accounts

Operators

Account filter fields

The posts scope

What gets rejected

Ordering

Reading the results

Continue from here

Search posts

API reference

​Query the identity

​Writing a query that qualifies

​Filter the accounts

​Operators

​Account filter fields

​The posts scope

​What gets rejected

​Ordering and pagination

​Ordering

​Pagination

​Reading the results

​Continue from here

Search posts

API reference

Query the identity

Writing a query that qualifies

Filter the accounts

Operators

Account filter fields

The posts scope

What gets rejected

Ordering and pagination

Ordering

Pagination

Reading the results

Continue from here