How to connect Mangools with Python

Search the Mangools location catalog by free-text query (e.g. "London", "Czech Republic", "California"). Returns a list of locations with their numeric `id` values, which are required as `location_id` parameter by most KWFinder, SERPChecker, and SiteProfiler tools. This endpoint is PUBLIC — no authentication required. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Get keywords related to a seed keyword, with search volume, CPC, PPC and (cached) keyword difficulty, sorted by relevance. Keyword difficulty (kd) is shown only where a cached value exists for that keyword+location; an absent kd means not cached — use kwfinder_get_keyword_details to compute it fresh. Location and language are optional. Returns a compact summary by default; set full=true for the raw response, or limit=N to cap the keyword list. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Get full metrics for a single keyword — keyword SEO difficulty, search volume, CPC/PPC — together with the organic SERP results and per-position click-through rates. Counts toward the SERP-lookups quota; identical requests within 24h are reused from cache. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Get the keywords a given URL or domain ranks for in organic search, sorted by estimated organic visits (highest-impact keyword first). Also returns the competing domains that share the most keywords. Up to 1,000 keywords per request. Pass location_id to target a country (resolve it with mangools_search_locations). Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Returns a list of domains that compete with the specified URL/domain for organic keywords. ### Limits Requires a GET or POST /kwfinder/competitor-keywords lookup for the same url and location_id within the last 24 hours; otherwise it answers HTTP 422 with the message No result. It does not count towards any pool. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Suggest keywords a URL, domain or subdomain could target, derived from the keywords it already ranks for (handy when setting up a new SERPWatcher tracking). Pass location_id to target a country (resolve it with mangools_search_locations). Counts toward the Keyword-lookups quota. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

Get keyword difficulty (KD) URL metrics for a specific URL — the URL authority score used as an input signal when calculating KWFinder's keyword difficulty. ### Limits Counts toward the daily kw-url-metrics pool in GET /kwfinder/limits. Identical requests within 24 hours are reused from cache. (Pace requests: the Mangools API allows only a few calls per short period.)

Get your current API usage and remaining limits across every Mangools resource — Keyword lookups, SERP lookups, Backlink rows, Tracked keywords, and more. Keyword API accounts also get an api_quota object: a separate API & MCP quota for keyword (related-keywords) and SERP (serps) lookups, each with limit, remaining and reset. Free and Free+ accounts eligible for the one-time API & MCP welcome bonus also get a permanent_credits object: the bonus keyword (related-keywords) and SERP (serps) lookups, each with limit and remaining. API & MCP requests spend these first, at 1 request = 1 lookup, and they never reset. Useful for quota checks before sending expensive requests. (Pace requests: the Mangools API allows only a few calls per short period.)

Get all keyword lists saved on your account, sorted newest first. Each list returns its id, name and the ids of the keywords it contains. Use kwfinder_get_list to load the full keyword data for a specific list. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Look up SEO metrics for a caller-supplied set of keywords (up to 700 per request): keyword difficulty, search volume, CPC/PPC and SERP context. Pass location_id for localized search volumes (resolve it with mangools_search_locations). Counts toward the Keyword-lookups quota; identical requests within 24h are reused from cache. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Find the keywords your competitors rank for but your domain does not — the classic SEO content-gap analysis. Compare your domain against 1-5 competitor domains for a given location. Counts toward the Keyword-lookups quota. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Deprecated — no fresh data since January 2025.] Previously returned monthly search-volume trends for a keyword (sourced from Google Trends). Cached results are still served; uncached queries return an empty data array. For search-volume history, rely on kwfinder_search_related_keywords / kwfinder_get_keyword_details instead. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the history of your recent keyword difficulty URL lookups performed through `/kwfinder/kd/url-metrics`. Each entry includes the URL and the URL authority score that was returned at the time — useful for rebuilding a "recent URL metrics" panel in a client. (Pace requests: the Mangools API allows only a few calls per short period.)

Get your last 100 KWFinder lookups, oldest first. Each entry has a type t: 0 related keywords (with kw, language, rank, rank_ts and location), 1 competitor keywords (with url and location), 2 keyword gap. (Pace requests: the Mangools API allows only a few calls per short period.)

Fetch full keyword data for a set of keywords by their Mangools keyword_ids. Returns a JSON array of keyword objects (keys include kw, sv, lid, cpc, ppc, seo, msv). keyword_ids come from a keyword-producing tool (related keywords, competitor keywords, suggestions, keyword import or keyword details). Optionally restrict fields via fields (kw, sv, lid, cpc, ppc, seo, msv). Unknown IDs are silently dropped. Free — does not consume lookup quota. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Create a new keyword list on your account. Required fields: * `name` — list name * `keyword_ids` — array of keyword IDs to populate the list (may be empty to create an empty list) Keyword IDs typically come from previous KWFinder lookups such as `/kwfinder/related-keywords` or `/kwfinder/keyword-imports`. An account can hold up to 10,000 lists; creating more answers HTTP 422. (Pace requests: the Mangools API allows only a few calls per short period.)

Get a single saved keyword list together with the full keyword data (search volume, CPC, PPC, keyword difficulty, location) for every keyword in it. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Rename an existing keyword list. Required field: * `name` — new list name Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

[Irreversible] Delete a keyword list. The list is removed from your account; keyword data referenced by the list is unaffected and remains available in other lookups. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Get a detailed SERP for a keyword in a given location: the organic and paid results plus all detected SERP features (rich snippets). For each organic result you get the URL, title, description, CTR, SEO metrics (Moz DA/PA, Majestic Citation/Trust Flow, referring domains, backlinks) and its above-the-fold visibility. Also returns the total result count and a link to a stored SERP snapshot image (kept 60 days). Pass location_id to localize (0 = any; resolve specific locations with mangools_search_locations); platform_id 1 = desktop, 2 = mobile. Returns a compact summary by default; set full=true for the raw SERP including layout geometry and every metric field, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Force a fresh re-parse of the SERP for a keyword/location instead of reusing the cached lookup, then return the same detailed SERP as serpchecker_get_serp (organic + paid results, SERP features, per-result SEO metrics, snapshot link). Consumes a SERP lookup. Pass location_id (0 = any) and platform_id (1 = desktop, 2 = mobile). Returns a compact summary by default; set full=true for the raw SERP, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Get SEO metrics for a specific URL — MOZ Domain Authority and Page Authority, plus Majestic Citation Flow and Trust Flow. Useful for enriching competitor URLs without running a full SERP lookup. ### Limits Counts toward the daily sch-url-metrics pool in GET /kwfinder/limits. Identical requests within 24 hours are reused from cache. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the history of your recent SERP lookups performed through `/serpchecker/serps`. Each entry includes the queried keyword and location — useful for rebuilding a "recent searches" panel in a client. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the rendered snapshot image of a SERP previously fetched with serpchecker_get_serp (or serpchecker_reset_serp). Pass the serp_snapshot_id from that response (format `<id>.<YYYY-MM-DD>`); snapshots are kept for ~60 days. Returns the screenshot as a base64 PNG. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Create a rank tracking for one domain on a single search location and platform; its keywords are queued for crawl and default weekly/monthly email reports are generated. A duplicate domain/location/platform returns HTTP 409. For multiple locations or platforms in one call, use serpwatcher_create_multiple_trackings. (Pace requests: the Mangools API allows only a few calls per short period.)

List all rank trackings owned by your account (newest first), each with its location and current tracked-keyword count. Pass is_with_deleted=true to also include previously deleted trackings. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Create rank trackings for a single domain across multiple search locations and platforms in one call. For a single location/platform, use serpwatcher_create_tracking. (Pace requests: the Mangools API allows only a few calls per short period.)

[Irreversible] Delete a rank tracking and all its tracked keywords. Irreversible. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

Get a lightweight snapshot of a tracking with its tracked-keyword list for the from/to range — each keyword with its id, text, currently ranking URL, tags and last-check time. Rank history and aggregated stats are omitted; use serpwatcher_get_tracking_stats for those. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

Get aggregated rank stats and per-keyword rank data for a tracking over a from/to range: current/best/average rank, rank and visit deltas, sampled rank history, Map Pack and Featured Snippet presence, detected SERP features, plus overlapping annotations. Optionally pass kwIds to limit to a subset of keywords. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

List all tracked keywords for a tracking, each enriched with search volume and monthly search volume. Pass is_with_deleted=true to include previously deleted keywords. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Add new keywords to an existing tracking. Request body: * `keywords` — array of keyword strings to add * `tag_ids` — optional array of tag IDs to assign to every added keyword (tags must already exist on the tracking) Keywords already tracked on this tracking are not re-added — their tags are simply extended with the provided ones. Only truly new keywords count against your tracked-keyword limit. The response returns both existing and newly added keywords in a single merged list. (Pace requests: the Mangools API allows only a few calls per short period.)

[Irreversible] Remove one or more tracked keywords from a tracking; pass their IDs in tracked_keyword_ids (non-empty array). Irreversible; the tracking stats are flagged for recomputation. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the full rank detail for one tracked keyword: ranking URLs split across organic, Map Pack and Featured Snippet, the daily rank series over the from/to window, current and previous search volume, a SERP snapshot link, and assigned tags. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

Get all scheduled email reports configured on a tracking (weekly, monthly, and rank-change alerts), sorted by creation date (newest first). Each report includes its type, name and the list of recipient email addresses. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Configure a new scheduled email report or rank-change alert for a tracking. Required fields: * `name` — human-readable report name * `type` — report type (weekly, monthly or rank-change alert) * `emails` — non-empty array of recipient email addresses * `triggers` — optional array of trigger types for rank-change alert reports (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Update the configuration of an existing scheduled email report — change its name, type, recipient emails list or triggers. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

[Irreversible] Remove a scheduled email report from a tracking. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Create a user annotation pinned to a specific date on the tracking timeline. Annotations are rendered as markers on rank history charts and help explain ranking changes (site launches, marketing campaigns, algorithm updates, etc.). Required fields: * `date` — annotation date in `YYYY-MM-DD` format * `text` — annotation text * `nonShareable` — optional boolean; when `true` the annotation is hidden from shared dashboard links (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Update an existing user annotation on a tracking — change its text, date (`YYYY-MM-DD`) or `nonShareable` flag. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

[Irreversible] Delete a user annotation from a tracking's timeline. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

List all keyword tags owned by your account across every tracking (newest first). Tags are color-coded labels used to organize tracked keywords and filter rank stats. For a list scoped to one tracking, use serpwatcher_list_tracking_tags. (Pace requests: the Mangools API allows only a few calls per short period.)

List all tags scoped to a specific tracking (newest first). For a cross-tracking list, use serpwatcher_list_tags. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Create a new tag on a tracking. Required fields: name (label) and color. Once created, attach tags to tracked keywords with serpwatcher_assign_tags. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Update an existing tag — change its `name` and/or `color`. The change is reflected everywhere the tag is rendered (keyword lists, statistics, email reports). Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Attach one or more tags to one or more tracked keywords in a single call. Both `keyword_ids` (tracked keyword IDs) and `tag_ids` are required. Existing tag assignments are preserved — the provided tags are merged with the current set so duplicates are avoided. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Detach one or more tags from one or more tracked keywords in a single call. Both `keyword_ids` (tracked keyword IDs) and `tag_ids` are required. Tags not currently assigned are ignored silently. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Get SEO metrics for a specific URL, domain or subdomain — Citation Flow, Trust Flow, referring domain and backlink counts sourced from Majestic. Useful for quickly evaluating a target's link authority before pulling a full backlink profile (counts toward your Backlink rows limit; identical requests within 24 hours are reused from cache). Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Get a list of backlinks for a specific URL, domain or URL path (up to 500 per page; paginate with the page parameter for more). Tip: set links_per_domain to 1 to get the most quality backlinks. Each returned link is counted toward your Backlink rows limit. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Star or unstar a backlink in your favorites. Pass favorite=true to add or false to remove. link_id is the _id of a link from linkminer_get_backlinks. (Pace requests: the Mangools API allows only a few calls per short period.)

Get all favorite-link lists saved on your account, sorted by last update (newest first). Favorite lists are per-target groupings of backlinks you have starred on linkminer_get_backlinks results. Each list includes its target domain, id and update timestamp. (Pace requests: the Mangools API allows only a few calls per short period.)

[Irreversible] Delete a favorite-link list from your account. Does not affect the underlying backlinks returned by linkminer_get_backlinks. Returns HTTP 204. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the history of your recent backlink lookups performed through linkminer_get_backlinks. Each entry includes the target URL, source type (all / new / lost) and the links_per_domain parameter that was used — useful for rebuilding a "recent searches" panel in a client. (Pace requests: the Mangools API allows only a few calls per short period.)

Get all full backlink CSV exports you have created, sorted by creation date (newest first). Each entry describes the target URL, the filters that were applied, the cost and the processing state. Once an export is ready, a `downloadURL` pointing to the generated CSV is included. The download link is returned for 60 days after the export completes. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Create a full-backlink CSV export job for a target URL, domain or subdomain. Call linkminer_suggest_export first to get the available target variants and the estimated cost, then pass the chosen url here. The export runs asynchronously — poll linkminer_list_exports to track state and to obtain the downloadURL once it completes. Note: the export cost is subtracted from the account's Backlink rows limit. (Pace requests: the Mangools API allows only a few calls per short period.)

[Consumes paid quota] Get the headline SEO metrics for a URL, domain or subdomain: Moz Domain Authority and Page Authority, Majestic Citation Flow and Trust Flow, the current TopRank rank, referring IPs and Facebook shares (each with history back to 2016 where available). Pass the target in the `url` parameter (a full URL, domain or subdomain — not a `domain` parameter). Call this first for any URL you then query with the audience, backlink-profile, top-content or competitors tools (they require a recent overview lookup). Returns a compact summary by default; set full=true for the raw response (including all history time series). This summary has no list-shaped section, so limit has no effect here. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the backlink profile for the URL, domain or subdomain passed in the `url` parameter (not a `domain` parameter); a domain request returns whole-domain stats. Includes total backlinks and referring domains/IPs, Citation/Trust Flow, the top referring domains and the top anchor texts. Requires a siteprofiler_get_overview lookup for the same url within the last 24 hours first, otherwise the API returns HTTP 429 "Not in history". Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the top-performing pages (by backlink metrics) for the URL, domain or subdomain passed in the `url` parameter (not a `domain` parameter). Each page includes its Citation/Trust Flow, referring domains and backlink count. Requires a siteprofiler_get_overview lookup for the same url within the last 24 hours first, otherwise the API returns HTTP 429 "Not in history". Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

Find the domains competing with the URL, domain or subdomain passed in the `url` parameter (not a `domain` parameter). Each competitor includes its TopRank rank, an overlap score, referring IPs and Facebook shares. Requires a siteprofiler_get_overview lookup for the same url within the last 24 hours first, otherwise the API returns HTTP 429 "Not in history". Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the history of your recent SiteProfiler lookups from the last 30 days. Returns a list of the analyzed URLs or domains — useful for rebuilding a "recent analyses" panel. Takes no parameters. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the list of AI models available for brand monitoring (ChatGPT, Gemini, Claude, and others). Each entry includes its numeric id, full model path (provider/name), display name and provider. Use the returned id values when configuring a monitor via ai_search_watcher_create_monitor. (Pace requests: the Mangools API allows only a few calls per short period.)

Get all AI Search Watcher brand monitors owned by your account. Each monitor describes a brand being tracked across AI answer engines — its name, domain, configured AI models and current visibility metrics. Use ai_search_watcher_get_monitor for the full details and analytics of a specific monitor. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Create a new AI Search Watcher brand monitor — a tracked setup measuring how often a brand is mentioned and cited by AI answer engines (ChatGPT, Gemini, Claude, Google AI Overview). Pick numeric model ids from ai_search_watcher_list_models, resolve location_id with mangools_search_locations, and optionally seed prompts with ai_search_watcher_generate_prompts. (Pace requests: the Mangools API allows only a few calls per short period.)

Get analytics for a single AI brand monitor (by id from ai_search_watcher_list_monitors): how often the brand is mentioned across the configured AI models and prompts, the citation sources the models return, sentiment signals, and visibility over time. Optional models (comma-separated model IDs, 0 for all) and from/to (YYYY-MM-DD) narrow the metrics. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many per-model/citation items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Irreversible] Delete an AI Search Watcher brand monitor from your account together with its prompts, reports and tags. The monitor stops collecting responses immediately, and its data is no longer returned by the API. Returns HTTP 200 with an empty object on success. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Generate suggested monitoring prompts and a brand-perception summary for a brand — useful during monitor onboarding so the user does not have to write AI Search Watcher prompts manually. Runs the AI models, so it consumes plan quota. Feed the returned prompts into ai_search_watcher_create_monitor or ai_search_watcher_add_monitor_prompts. (Pace requests: the Mangools API allows only a few calls per short period.)

Get metrics for a single monitoring prompt (by id from ai_search_watcher_list_monitor_prompts): how each configured AI model responds to it, brand mention counts, the citation URLs extracted from the responses, and visibility over time. Optional from/to (YYYY-MM-DD) and models (model IDs) filter the metrics. Returns a compact summary by default; set full=true for the raw response, or limit=N to change how many per-model/citation items are listed. (Pace requests: the Mangools API allows only a few calls per short period.)

[Irreversible] Delete one or more monitoring prompts across monitors in a single bulk call. Request body: * `prompt_ids` — non-empty array of prompt IDs to delete Remaining prompts on the affected monitors continue collecting responses on the next scheduled run. The response returns `deleted_count`. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the list of monitoring prompts attached to a monitor. Each prompt entry includes its id, text, tags, creation and update timestamps, its metrics for the requested date range and its Google AI Overview information. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Add one or more new prompts to an existing AI brand monitor (by id from ai_search_watcher_list_monitors). Generate candidate prompts first with ai_search_watcher_generate_prompts if needed. (Pace requests: the Mangools API allows only a few calls per short period.)

Get the current configuration of a monitor — brand name, brand variations, domain, location, configured AI models, language, active email reports and notification settings. Useful for populating a settings form in a client. (Pace requests: the Mangools API allows only a few calls per short period.)

[Modifies user data] Update the configuration of an existing monitor: brand name, brand variations, domain, AI model list and email reports. Location, platform and language cannot be changed. Only the fields present in the request body are updated, and any other field is rejected with HTTP 422. (Pace requests: the Mangools API allows only a few calls per short period.)

Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.