solari-sdk

Python client for the SOLARI API — creator and brand intelligence across Instagram and TikTok, plus Meta Threads profiles and posts. Standard library only; Python 3.9+; ships py.typed.

pip install solari-sdk

Quickstart

from solari_sdk import Solari

solari = Solari()  # reads SOLARI_TOKEN; or Solari(token="...")

hits = solari.tools.catalog.instagram.account.search(query="nike", limit=3)
brand = solari.tools.insight.instagram.brand.overview(username="nike")
thread = solari.tools.fetch.threads.post(url="https://www.threads.com/@zuck/post/Ddt7cL5EfUG")
tools = solari.list_tools()

For Threads, solari.tools.fetch.threads.account.search(query=...) finds handles by name and .post.search(query=...) returns Threads' top posts for a keyword (both live on every call, one page, not cached); .account(username=...), .posts(username=..., limit=...), and .post(url=...) (or code=...) read the profile, its newest posts, or one post with its first replies straight from the response. A first collection takes 5 to 30 seconds; repeat calls within an hour return the stored copy unless refresh=True.

For TikTok live search, solari.tools.fetch.tiktok.account.search(query=...) finds accounts by name and .post.search(query=...) finds videos by keyword, in TikTok's own order (live on every call, not cached, nothing stored). When has_more is true, pass next_cursor back as cursor= with the same query for the next page. Account hits carry account_id when already in the catalog, else .account(username=...) adds one; .post(url=...) collects and stores a video hit.

Follower and engagement trends: solari.tools.catalog.instagram.account.history(username=..., since=...) returns follower, following, and post counts at each collection (captured_at) plus current.collected_at, and solari.tools.catalog.instagram.content.history(username=..., posted_since=...) (or post_ids=, slugs=, urls=) returns each post's like, comment, play, and reshare counts over time. One point per UTC day by default (granularity="all" for every collection); gaps between points are normal.

Create an API key on your SOLARI My page (long-lived, solari_sk_…, shown once), or mint a short-lived token with solari auth token on a machine signed in to the solari CLI.

Typed tools

solari.tools is generated from the SOLARI tool registry: every tool is a real method with keyword-only, typed parameters (Literal[...] for enums), so pyright and mypy catch a missing required argument, a misspelled keyword, or a wrong enum value before anything runs, and your editor completes the paths.

solari.tools.catalog.instagram.account.search(query="nike", query_type="bio")
solari.tools.catalog.instagram.account.search(limit=3)  # type checker: missing "query"
solari.tools.catalog.instagram.account.search(query="nike", query_type="fuzzy")  # type checker: not a Literal value

Tool responses are JSON (Any) whose shape is documented per tool at solari.sh/docs.

solari.call(name, arguments=None, **kwargs) runs any tool by name, including the per-account solari_apps_* tools that are not in the generated catalog; solari.dynamic.<any>.<path>(**kwargs) spells such a call as a path without type checking.

API

• Solari(token=None, base_url="https://solari.sh", timeout=150, user_agent=None, transport=None)
• tools.<family>.<platform>.<group>.<name>(**kwargs) — typed tool calls; segments mirror the solari_ tool names.
• call(name, arguments=None, **kwargs) — run a tool by name and get its JSON payload back.
• list_tools() — every tool the signed-in account can call, with its JSON input schema.
• get_tool(name) — one tool.
• me() — the identity behind the token.
• dynamic — untyped path proxy for tools that are not in the generated catalog.
• SOLARI_TOOL_NAMES, SolariTools — the generated catalog.

Errors raise SolariError with status, code, message, tool, retry_after_seconds, and a retryable property (429, 502, 503, 504).

Development

python3 -m unittest discover -s tests -v
uvx pyright
uvx mypy --strict solari_sdk tests/typed_usage.py

solari_sdk/_tools.py is produced from the MCP worker's tool registry by pnpm run sdk:generate in cf-workers/solari-mcp; CI fails when it is stale.