Quickstart - Klint

Three steps.

1

Get an API key

Create a key in the Klint dashboard. Export it:

export KLINT_API_KEY="klint_..."

Every request sends Authorization: Bearer $KLINT_API_KEY. See Authentication.

An account-free trial is planned. Until it is available, create your key in the dashboard.

2

Search posts

One request with a semantic query, a post filter, and nested author filters:

curl
Python
TypeScript

curl -X POST "https://api.tryklint.ai/v1/instagram/posts/search" \
  -H "Authorization: Bearer $KLINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "post": {
    "query": "UGC-style grooming-product demonstrations",
    "filters": {
      "posted_at": {
        "gte": "2026-06-01T00:00:00Z"
      },
      "format": {
        "in": ["reel"]
      }
    },
    "author": {
      "filters": {
        "followers_count": {
          "gte": 5000,
          "lte": 50000
        },
        "niches": {
          "contains_any": ["pets"]
        }
      }
    }
  },
  "limit": 10
}'

import os, requests

resp = requests.post(
    "https://api.tryklint.ai/v1/instagram/posts/search",
    headers={"Authorization": f"Bearer {os.environ['KLINT_API_KEY']}"},
    json={
  "post": {
    "query": "UGC-style grooming-product demonstrations",
    "filters": {
      "posted_at": {
        "gte": "2026-06-01T00:00:00Z"
      },
      "format": {
        "in": ["reel"]
      }
    },
    "author": {
      "filters": {
        "followers_count": {
          "gte": 5000,
          "lte": 50000
        },
        "niches": {
          "contains_any": ["pets"]
        }
      }
    }
  },
  "limit": 10
},
)
results = resp.json()

const resp = await fetch("https://api.tryklint.ai/v1/instagram/posts/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KLINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "post": {
      "query": "UGC-style grooming-product demonstrations",
      "filters": {
        "posted_at": {
          "gte": "2026-06-01T00:00:00Z"
        },
        "format": {
          "in": ["reel"]
        }
      },
      "author": {
        "filters": {
          "followers_count": {
            "gte": 5000,
            "lte": 50000
          },
          "niches": {
            "contains_any": ["pets"]
          }
        }
      }
    },
    "limit": 10
  }),
});
const results = await resp.json();

Full response

{
  "request_id": "req_example_01",
  "data": [
    {
      "id": "ig_post_8f3k2",
      "shortcode": "DLm2XwYv4Qk",
      "web_url": "https://www.instagram.com/reel/DLm2XwYv4Qk/",
      "posted_at": "2026-07-06T14:02:00Z",
      "observed_at": "2026-07-14T16:10:00Z",
      "format": "reel",
      "primary_language": "en",
      "caption": "The brush that finally fixed our shedding problem 🐕 One week of daily passes and the couch is fur-free. Grab 20% off with code GROOM20 — link in bio. #doggrooming",
      "hashtags": [
        "doggrooming"
      ],
      "caption_mentions": [],
      "audio": {
        "id": "ig_audio_7m4q",
        "instagram_id": "587784541076604",
        "type": "music",
        "title": "Birthday Wish",
        "attribution": {
          "display_name": "Shuba",
          "account": null
        },
        "duration_seconds": 153.76,
        "web_url": "https://www.instagram.com/reels/audio/587784541076604/"
      },
      "content_summary": "A creator demonstrates a deshedding brush on a dog, describes a less-messy grooming routine, shows the result, and directs viewers to a discount in the Account bio.",
      "topics": [
        "dog_grooming",
        "at_home_pet_care"
      ],
      "creative_formats": [
        "talking_head",
        "product_demonstration",
        "creator_testimonial"
      ],
      "hook": {
        "construction": "The creator holds the brush beside a visibly shedding dog, states that it changed the grooming routine, and displays a seven-day result claim.",
        "devices": [
          "problem_callout",
          "direct_promise"
        ],
        "modalities": [
          "visual",
          "spoken",
          "on_screen_text"
        ]
      },
      "key_messages": [
        {
          "summary": "The brush is presented as making at-home shedding cleanup easier.",
          "roles": [
            "claim",
            "benefit",
            "use_case"
          ],
          "presentation": "asserted"
        }
      ],
      "proofs": [
        {
          "summary": "The creator demonstrates brushing the dog and shows the collected hair.",
          "mechanisms": [
            "live_product_demonstration",
            "result_reveal"
          ],
          "cited_source_types": []
        }
      ],
      "offers": [
        {
          "summary": "20% off with a stated promo code.",
          "types": [
            "discount",
            "promo_code"
          ],
          "stated_terms": [
            "20% off",
            "GROOM20"
          ]
        }
      ],
      "calls_to_action": [
        {
          "summary": "Use the link in the Account bio.",
          "actions": [
            "visit_profile_link"
          ],
          "stages": [
            "closing"
          ],
          "modalities": [
            "spoken",
            "on_screen_text",
            "caption"
          ]
        }
      ],
      "narrative_structure": {
        "description": "Problem framing, product demonstration, result reveal, then offer and CTA.",
        "patterns": [
          "problem_solution",
          "demonstration_to_result",
          "offer_close"
        ]
      },
      "has_paid_partnership_label": false,
      "paid_partners": [],
      "commercial_contexts": [
        "promo_code",
        "seller_behavior"
      ],
      "comments_enabled": true,
      "views": 412000,
      "likes": 28600,
      "comments": 354,
      "engagement_rate_by_views": 0.0703,
      "view_ratio_to_account_baseline": 6.2,
      "author": {
        "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",
        "followers_count": 21400,
        "is_verified": false
      },
      "coauthors": []
    },
    {
      "id": "ig_post_9m3t",
      "shortcode": "DMq7RwXk2Pd",
      "web_url": "https://www.instagram.com/reel/DMq7RwXk2Pd/",
      "posted_at": "2026-06-24T19:15:00Z",
      "observed_at": "2026-07-14T13:40:00Z",
      "format": "reel",
      "primary_language": "en",
      "caption": "POV: shedding season with a husky 😅 This grooming glove is the only thing keeping our couch alive. #huskylife #sheddingseason #doggrooming",
      "hashtags": [
        "huskylife",
        "sheddingseason",
        "doggrooming"
      ],
      "caption_mentions": [],
      "audio": {
        "id": "ig_audio_2b8c",
        "instagram_id": null,
        "type": "original_sound",
        "title": "Original audio",
        "attribution": {
          "display_name": "brodyandbear",
          "account": {
            "id": "ig_account_3d6p",
            "handle": "brodyandbear",
            "display_name": "Brody & Bear",
            "web_url": "https://www.instagram.com/brodyandbear/",
            "avatar_url": "https://media.tryklint.ai/accounts/ig_account_3d6p/avatar",
            "followers_count": 12400,
            "is_verified": false
          }
        },
        "duration_seconds": 18.9,
        "web_url": null
      },
      "content_summary": "A dog owner films a casual at-home demonstration of a grooming glove on a shedding husky, showing the removed undercoat and joking about protecting the couch.",
      "topics": [
        "dog_grooming",
        "at_home_pet_care"
      ],
      "creative_formats": [
        "product_demonstration"
      ],
      "hook": {
        "construction": "A point-of-view framing of shedding season opens on a husky mid-shed before the owner pulls out the grooming glove.",
        "devices": [
          "relatable_scenario"
        ],
        "modalities": [
          "visual",
          "on_screen_text"
        ]
      },
      "key_messages": [
        {
          "summary": "The grooming glove is presented as an easy way to control husky shedding at home.",
          "roles": [
            "claim",
            "benefit"
          ],
          "presentation": "asserted"
        }
      ],
      "proofs": [
        {
          "summary": "The owner demonstrates the glove on the husky and shows the removed fur.",
          "mechanisms": [
            "live_product_demonstration",
            "result_reveal"
          ],
          "cited_source_types": []
        }
      ],
      "offers": [],
      "calls_to_action": [],
      "narrative_structure": null,
      "has_paid_partnership_label": false,
      "paid_partners": [],
      "commercial_contexts": [],
      "comments_enabled": true,
      "views": 156000,
      "likes": 9800,
      "comments": 412,
      "engagement_rate_by_views": 0.0655,
      "view_ratio_to_account_baseline": null,
      "author": {
        "id": "ig_account_3d6p",
        "handle": "brodyandbear",
        "display_name": "Brody & Bear",
        "web_url": "https://www.instagram.com/brodyandbear/",
        "avatar_url": "https://media.tryklint.ai/accounts/ig_account_3d6p/avatar",
        "followers_count": 12400,
        "is_verified": false
      },
      "coauthors": []
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Every returned post satisfies the query and every filter. Weak matches never pad the list. has_more and next_cursor continue the result set; see pagination.

3

Read one post in full

Follow a result’s id to the complete post, with ordered media items, transcript, on-screen text, and visual descriptions:

curl "https://api.tryklint.ai/v1/instagram/posts/ig_post_8f3k2" \
  -H "Authorization: Bearer $KLINT_API_KEY"

Next

Filter grammar

Operators, composition rules, and what gets rejected.

Search accounts

Find accounts by who they currently appear to be.

Klint for coding agents

The whole contract on one agent-ready page.

Errors

Every error, what causes it, and whether to retry.