--- title: Botify API Integration on Truto slug: botify category: Analytics canonical: "https://truto.one/integrations/detail/botify/" --- # Botify API Integration on Truto **Category:** Analytics **Status:** Beta ## MCP-ready AI tools Truto exposes 48 tools for Botify that AI agents can call directly. - **list_all_botify_analyses** — List all Botify analyses for a project. Returns each analysis with slug, name, status, url, date_launched, date_finished, and additional crawl metadata. Required: username, project_slug. - **botify_analyses_pause** — Pause a running Botify analysis for a project. Returns the analysis object with slug, name, status, url, date_launched, and additional crawl metadata. Required: username, project_slug, analysis_slug. - **botify_analyses_resume** — Resume a paused Botify analysis for a project. Returns the analysis object with slug, name, status, url, date_launched, and additional crawl metadata. Required: username, project_slug, analysis_slug. - **get_single_botify_analysis_by_id** — Get a single Botify analysis by id. Returns: user, owner, slug, name, friendly_name, url, status, computing_revision, features, urls_done, urls_in_queue, config, date_launched, date_finished, date_last_modified, date_created, date_crawl_done, failures, red_button_domain, import_keywords_data, import_keywords_data_by_country, crawl_launch_type, to_be_deleted_at, comparable, excluded_from_trends,…. Required: id, username, project_slug. - **create_a_botify_create_launch** — Create and launch an analysis for a Botify project. Returns the created analysis launch response object. Required: username, project_slug. - **list_all_botify_lights** — List all analyses for a Botify project in light format. Returns: next, previous, count, results, page, size. Required: username, project_slug. - **list_all_botify_crawl_statistics** — Get global crawl statistics for a Botify analysis. Returns a crawl statistics object whose attributes contain analysis-level crawl metrics defined in the upstream Botify OpenAPI schema. Required: username, project_slug, analysis_slug. - **list_all_botify_crawl_statistics_times** — List Botify crawl statistics grouped by time frequency (1mn, 5mn, or 60mn) for a specific analysis. Returns the data object containing time-grouped crawl metric arrays as defined by the upstream CrawlStatisticsTime schema. Required: username, project_slug, analysis_slug, frequency. - **list_all_botify_crawl_statistics_urls** — List the 1000 latest URLs crawled during a Botify analysis, either all crawled URLs or only those with HTTP errors depending on the list_type. Returns an array of URL records including the url. Limited to 1000 results. Required: username, project_slug, analysis_slug, list_type. - **list_all_botify_ganalytics_orphan_urls** — List Google Analytics orphan URLs for a Botify analysis — URLs that received visits from the selected traffic source but were not crawled by Botify. Returns: next, previous, count, results, page, size. Legacy endpoint; medium must be organic or social with a matching source value. Required: username, project_slug, analysis_slug, medium, source. - **list_all_botify_links_percentiles** — Get inlinks percentiles. Returns: domain, percentiles. Required: username, project_slug, analysis_slug. - **list_all_botify_pagerank_losts** — List lost pagerank entries for a Botify analysis. Returns: non_crawled, external, robots_txt. Required: username, project_slug, analysis_slug. - **list_all_botify_scoring_summaries** — Get the scoring summary for a specific Botify analysis. Returns the scoring summary object for the analysis. Required: username, project_slug, analysis_slug. - **list_all_botify_search_console_stats** — List Google Search Console clicks and impressions per day for a Botify analysis. Returns: stats. Required: username, project_slug, analysis_slug. - **list_all_botify_sitemaps_reports** — Get the sitemaps report for a Botify analysis, providing global information about sitemaps found during the crawl such as sitemaps indexes and invalid sitemaps URLs. Returns the SitemapsReport object. Required: username, project_slug, analysis_slug. - **list_all_botify_samples_out_of_configs** — List sample URLs found in Botify sitemaps but outside the crawl perimeter defined for the project (e.g., disallowed domains, subdomains, or protocols). Returns: next, previous, count, results, page, size. Required: username, project_slug, analysis_slug. - **list_all_botify_samples_sitemap_onlies** — List URLs found in your sitemaps, within the project allowed scope (allowed domains/subdomains/protocols), but not found by the Botify crawler, for a given Botify analysis. Returns: next, previous, count, results, page, size. Required: username, project_slug, analysis_slug. - **list_all_botify_top_domains_domains** — List top domains found in a Botify analysis. Returns: next, previous, count, results, page, size. Required: username, project_slug, analysis_slug. - **list_all_botify_top_domains_subdomains** — List top subdomains for a Botify analysis. Returns a paginated collection with next, previous, count, results, page, and size. Required: username, project_slug, analysis_slug. - **list_all_botify_visits_orphan_urls** — List orphan URLs in a Botify analysis — URLs that received visits from a search engine or social source per Google Analytics but were not crawled by the Botify crawler. Returns: next, previous, count, results, page, size. Medium and source must form a valid pair (e.g. organic with google, or social with facebook). Required: username, project_slug, analysis_slug, medium, source. - **list_all_botify_segments** — List segments (segments feature public metadata) for a Botify analysis. Returns: next, previous, count, results, page, size. Required: username, project_slug, analysis_slug. - **list_all_botify_staticfiles_robots_txt_indexes** — List all robots.txt files found on a Botify project's domains for a given analysis. The object is null for virtual robots.txt. Returns: next, previous, count, results, page, size. Required: username, project_slug, analysis_slug. - **get_single_botify_staticfiles_robots_txt_index_by_id** — Get the content of a specific robots.txt file from a Botify analysis by id. Returns: next, previous, count, results, page, size. Required: id, username, project_slug, analysis_slug. - **get_single_botify_url_by_id** — Gets the detail of an URL for an analysis. Required: id, username, project_slug, analysis_slug. - **list_all_botify_urls** — List Botify URLs for an analysis by executing a BQL query against the URLs collection. Returns URL detail records with id and datamodel-specific attributes; the attributes shape depends on the analysis's URLs Datamodel. Required: username, project_slug, analysis_slug. - **get_single_botify_urls_agg_by_id** — Run BQL aggregation queries against URLs in a Botify analysis. Accepts multiple queries in the request body (each with filters and aggs) and dispatches them, returning an array of query-dependent aggregation result objects whose structure reflects the dimensions and metrics defined in each BQL query. Required: username, project_slug, analysis_slug. - **list_all_botify_urls_ais** — Get AI suggestions for a specific URL within a Botify analysis. Returns the AI suggestions object with schema-specific fields. Required: username, project_slug, analysis_slug, url. - **list_all_botify_urls_datamodels** — Get the Botify Analysis datamodel describing the available URL fields for a specific analysis. Returns the datamodel object including attributes with analysis-specific field definitions whose shape depends on the crawl configuration and enabled features. Required: username, project_slug, analysis_slug. - **list_all_botify_urls_datasets** — List the available datasets (field groups) for a Botify analysis, used to discover queryable fields for BQL operations. Returns: datasets. Required: username, project_slug, analysis_slug. - **list_all_botify_urls_exports** — A list of the CSV Exports requests and their current status. Returns: job_id, job_url, job_status, nb_results, area, query, results, date_created. Required: username, project_slug, analysis_slug. - **create_a_botify_urls_export** — Creates a new UrlExport object and starts a task that will export the results into a csv. Returns the model id that manages the task. Returns: job_id, job_url, job_status, nb_results, area, query, results, date_created. Required: username, project_slug, analysis_slug. - **get_single_botify_urls_export_by_id** — Checks the status of an CSVUrlExportJob object. Returns json object with the status. Returns: job_id, job_url, job_status, nb_results, area, query, results, date_created. Required: id, username, project_slug, analysis_slug. - **list_all_botify_urls_htmls** — Get the HTML content of a specific URL within a Botify analysis. Returns the HTML content object for the requested URL from the crawl. Required: username, project_slug, analysis_slug, url. - **list_all_botify_jobs** — List all Botify jobs, optionally filtered by job type, project slug, or analysis slug. Returns: next, previous, count, results, page, size. - **create_a_botify_job** — Create a Botify job instance whose class depends on the job_type parameter sent. Returns: job_id, job_type, job_url, job_status, results, date_created, payload, user, metadata, crawl_date, project, analysis. Required: job_type, payload. - **get_single_botify_job_by_id** — Get a single Botify job by id. Returns: job_id, job_type, job_url, job_status, results, date_created, payload, user, metadata, crawl_date, project, analysis. Required: id. - **list_all_botify_projects** — List all active Botify projects for a user. Returns: next, previous, count, results, page, size. Required: username. - **list_all_botify_account_filters** — List all account saved filters for a Botify project. Returns each filter's name, identifier, filters, type, project_name, and created_date. Required: username, project_slug. - **list_all_botify_collections** — List all Botify collections for a project. Returns collection objects with their id and attributes containing collection-specific fields. Required: username, project_slug. - **get_single_botify_collection_by_id** — Get a single Botify collection by id including its datasets and field definitions. Returns: datasets, metadata. Required: id, username, project_slug. - **list_all_botify_filters** — List all saved filters for a Botify project, including each filter's name, ID, and filter value. Returns: name, filters, identifier, description, type, project_name, created_date. Required: username, project_slug. - **get_single_botify_filter_by_id** — Get a specific Botify project filter by id. Returns: name, filters, identifier, description, type, project_name, created_date, openapi, info, paths, security, servers, components. Required: id, username, project_slug. - **create_a_botify_query** — Run a query against project-level collections in Botify. Returns: next, previous, count, results, page, size. Required: username, project_slug, collections, query. - **list_all_botify_saved_explorers** — List all saved explorers for a Botify project. Returns each saved explorer with its uuid, name, type, description, query object, created_by and modified_by user details, and created_date and modified_date timestamps. Required: username, project_slug. - **create_a_botify_values_list_clone** — Clone all keyword groups of a Botify project to another project. Returns an empty 201 response on success. Required: username, project_slug, target_username, target_project. - **list_all_botify_user_datasources_summary_by_projects** — Get the datasources details for all projects of a Botify user. Returns: runnable, datasource, date_last_successful_revision, last_revision_status, stats, segments. Required: username. - **list_all_botify_user_projects** — List all active Botify projects for a user. Returns each project's name, slug, active status, date_created, url, timezone, last_analysis, current_settings, and associated user. Required: username. - **get_single_botify_project_urls_agg_by_id** — Execute multiple BQL aggregation queries across all completed analyses in a Botify project. Returns a dynamic aggregation results object with query-specific fields. nb_analyses is capped at 20. Required: username, project_slug. ## How it works 1. **Link your customer's Botify account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Botify.** The Proxy API is a 1-to-1 mapping of the Botify API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed enterprise SEO analytics into marketing dashboards** — BI and marketing analytics platforms can pull Botify crawl stats, orphan URLs, and BQL aggregations directly into their dashboards, letting customers correlate technical SEO health with revenue and pipeline data without leaving the product. - **Trigger crawls automatically from CMS or deployment events** — Headless CMS platforms and CI/CD tools can programmatically launch Botify analyses whenever large content batches ship, so customers get an immediate technical audit of newly published URLs. - **Power SEO incident alerting for site reliability tools** — Monitoring and alerting SaaS can poll Botify crawl statistics to detect spikes in 4xx/5xx errors, crawl drops, or sitemap regressions, and route alerts to on-call engineers before Google de-indexes affected pages. - **Guardrail CRO and A/B testing platforms against SEO regressions** — Experimentation platforms can compare Botify PageRank and internal link percentile data before and after a test deploys, warning customers if a navigation or template change is bleeding link equity from high-value pages. - **Automate technical SEO ticketing for engineering teams** — Ticketing and project management tools can query Botify sitemap reports and crawl statistics to auto-generate Jira or Linear issues for broken URLs, orphan pages, and indexability problems on high-value templates. ## What you can build - **One-click crawl launcher** — Let users kick off a new Botify analysis from your UI using create_a_botify_create_launch, with pause and resume controls wired to botify_analyses_pause and botify_analyses_resume. - **Orphan URL recovery workflow** — Surface URLs from list_all_botify_ganalytics_orphan_urls and list_all_botify_visits_orphan_urls that receive real traffic but aren't reachable via internal links, so users can prioritize fixes. - **Custom BQL query builder** — Use create_a_botify_query and get_single_botify_urls_agg_by_id to let users define aggregated SEO metrics (by depth, segment, or template) and render them as widgets inside your app. - **Async URL export pipeline into a data warehouse** — Schedule large URL-level exports via create_a_botify_urls_export and poll get_single_botify_urls_export_by_id to sync Botify datasets into Snowflake, BigQuery, or Redshift. - **Crawl health monitoring widget** — Combine list_all_botify_crawl_statistics, list_all_botify_crawl_statistics_times, and list_all_botify_crawl_statistics_urls to show real-time crawl error rates, speed, and coverage trends. - **PageRank and sitemap integrity alerts** — Poll list_all_botify_pagerank_losts and list_all_botify_sitemaps_reports to detect pages bleeding link equity or sitemap entries returning errors, and push alerts into Slack or ticketing tools. ## FAQs ### How do end users authenticate their Botify account? Truto handles the Botify auth flow for you, so your users connect their Botify workspace once and your app receives a managed connection. You don't need to store API tokens or handle refresh logic yourself. ### Can we trigger and control crawls programmatically? Yes. You can launch new analyses via create_a_botify_create_launch, and pause or resume running crawls with botify_analyses_pause and botify_analyses_resume — useful for CMS publish events or CI/CD hooks. ### Does Truto support Botify Query Language (BQL) aggregations? Yes. create_a_botify_query and get_single_botify_urls_agg_by_id let you run BQL aggregations to pull custom metrics grouped by depth, segment, status code, or any dimension Botify exposes. ### How do we handle very large URL datasets? For bulk data, use the async export pattern: call create_a_botify_urls_export to schedule the export, then poll get_single_botify_urls_export_by_id until it's ready. This is the recommended path for warehousing millions of URLs. ### Can we access log-file and Google Analytics cross-referenced data? Yes. Endpoints like list_all_botify_ganalytics_orphan_urls and list_all_botify_visits_orphan_urls expose URLs Botify has cross-referenced between crawl data and analytics, which is one of Botify's most differentiated datasets. ### How fresh is the data returned by the Botify API? Data freshness depends on when the underlying analysis was run in Botify — crawls are point-in-time snapshots rather than continuous streams. Trigger a new analysis via create_a_botify_create_launch when your users need up-to-date results. ## Related reading - [Connect Botify to ChatGPT: Automate SEO Audits & Crawl Management](https://truto.one/blog/connect-botify-to-chatgpt-automate-seo-audits-crawl-management/) — Learn how to connect Botify to ChatGPT using a managed MCP server. Automate SEO audits, crawl management, and complex BQL data queries with AI. - [Connect Botify to Claude: Analyze Search Performance & URL Insights](https://truto.one/blog/connect-botify-to-claude-analyze-search-performance-url-insights/) — Learn how to connect Botify to Claude using a Truto MCP server. This guide covers BQL query generation, rate limit handling, and automated SEO analysis workflows. - [Connect Botify to AI Agents: Run BQL Queries & Large-Scale Exports](https://truto.one/blog/connect-botify-to-ai-agents-run-bql-queries-large-scale-exports/) — Learn how to safely connect Botify to AI agents using Truto's /tools endpoint. Build autonomous workflows to run BQL queries and manage large-scale data exports.