GETInsights3–7 credits

Lead fit scoring

GET https://api.instagramapi.dev/v1/insights/profile/qualify

Scores how well an account matches your ideal-customer description. Pass `criteria` describing the lead you want (e.g. "US-based fitness coaches with 10k–100k followers selling online programs") and we score the profile + recent posts 0–100 with reasons and signals. Cost: 3–7 credits depending on how many posts are considered.

Build this with an AI agent

Paste this prompt into Claude, Codex, or any coding agent.

Parameters

Name	Type	Required	Description
handle	string	yes	An Instagram account. Accepts a username (`nike`), a numeric user id (`13460080`), or a full profile URL (`https://instagram.com/nike`). We resolve it automatically.
criteria	string	yes	Plain-English description of your ideal lead.
posts	number	no	Recent posts to consider (1–50). Defaults to 12.

Example request

curl "https://api.instagramapi.dev/v1/insights/profile/qualify?handle=nike&criteria=US%20fitness%20coaches%20selling%20online%20programs&posts=12" \
  -H "Authorization: Bearer $INSTAGRAMAPI_KEY"

const res = await fetch("https://api.instagramapi.dev/v1/insights/profile/qualify?handle=nike&criteria=US%20fitness%20coaches%20selling%20online%20programs&posts=12", {
  headers: { Authorization: `Bearer ${process.env.INSTAGRAMAPI_KEY}` },
});

res = requests.get("https://api.instagramapi.dev/v1/insights/profile/qualify?handle=nike&criteria=US%20fitness%20coaches%20selling%20online%20programs&posts=12",
    headers={"Authorization": f"Bearer {INSTAGRAMAPI_KEY}"})

Try it

Live request · uses 3 credits

API key

handle *string

criteria *string

postsnumber

Example responses

Switch tabs to see the body shape for success and each error status.

{
  "data": {
    "username": "nike",
    "criteria": "US fitness coaches selling online programs",
    "fit_score": 22,
    "verdict": "weak",
    "reasons": [
      "Global brand, not an individual coach",
      "No online-program offer in bio"
    ],
    "signals": {
      "positive": [
        "Fitness niche"
      ],
      "negative": [
        "Not a coach",
        "Enterprise account"
      ]
    },
    "recommended_action": "Skip. Does not match the ICP."
  },
  "meta": {
    "endpoint": "insights/profile/qualify",
    "request_id": "req_3f8a1c9e",
    "credits_charged": 3,
    "credits_remaining": 4987,
    "ms": 412
  }
}

{
  "error": {
    "code": "missing_parameter",
    "message": "Missing required parameter \"handle\".",
    "docs": "/docs/insights/profile/qualify"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid or has been revoked.",
    "docs": "/docs#authentication"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "You're out of credits. Top up to continue.",
    "docs": "/dashboard/billing"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "No public data for that request (private, deleted, or nonexistent). This is a billed request. We queried Instagram on your behalf.",
    "docs": "/docs/insights/profile/qualify"
  },
  "meta": {
    "request_id": "req_3f8a1c9e",
    "endpoint": "insights/profile/qualify",
    "credits_charged": 3,
    "credits_remaining": 4985
  }
}

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream data provider error. You were not charged. Please retry.",
    "docs": "/docs/insights/profile/qualify"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

Response fields

Fields returned under data on a 200 response. Every response also includes a meta object with billing info.

Field	Type	Description
username	string	The account's @handle.
criteria	string	The ideal-lead description you supplied, echoed back.
fit_score	number	How well the account matches your criteria (0–100).
verdict	string	Short label for the fit (e.g. strong / moderate / weak).
reasons	array<string>	Key reasons behind the score.
signals	object	Positive and negative signals the score is based on.
signals.positive	array<string>	Signals that support a good fit.
signals.negative	array<string>	Signals that count against the fit.
recommended_action	string	Suggested next step (e.g. pursue or skip).