Migrate from Conductor's Legacy Reporting API

Conductor Intelligence’s legacy Reporting API (the /v3/... endpoints) is being retired. This guide walks you through moving your scripts, data pipelines, and connections to Conductor’s API.

Overview

Key dates

Date	What happens
October 31, 2026	Deprecation communicated. The migration window begins.
January 15, 2027	End of life. The legacy Reporting API stops responding.

After January 15, 2027, calls to the legacy /v3/... endpoints will fail. Any report, dashboard, or data pipeline that still depends on them will stop updating.

Why migrate now

Simpler authentication. A single API token replaces the key, secret, and computed signature.
AI Search data. Get brand mentions, citations, sentiment, responses, and query fan-out alongside your traditional rankings.
One set of credentials. The same token works for the Data API, the Content API, and the configuration endpoints.
Actively maintained. New endpoints and fields ship to Conductor’s API only.

Who needs to act

You need to migrate if anything in your organization calls https://api.conductor.com/v3/... with the apiKey and sig query parameters. Check:

Custom scripts and data warehouse ETL jobs
Anything built on the conductor-api Python package
BI connectors, such as Domo or Looker Studio
n8n, Zapier, or other automations

The base URL is still https://api.conductor.com. Because the host doesn’t change, a legacy connection can look up to date when it isn’t. Check each integration’s request paths and how it authenticates, not just the host.

What’s different at a glance

	Legacy Reporting API	Conductor’s API
Authentication	API key + secret, with an MD5 signature passed as query parameters (valid within a 5-minute window)	API token passed as a Bearer token in the `Authorization` header
Request style	`GET` with path parameters (`/v3/{accountId}/...`)	`POST` with a JSON body
Execution	Synchronous; designed for bulk downloads	Asynchronous: submit, receive an `executionId`, then poll for results
Pagination	None	`nextPageId`
Response shape	Named JSON objects	A `schema` array plus positional `results` rows
Date handling	`timePeriodId` or `CURRENT`	Explicit date ranges aligned to `collection_frequency`
Rate limits	5,000 calls/day and 2 calls/second per key	5,000 calls/day and 2 calls/second per key
Data coverage	Rankings, search volume, and configuration	Rankings, search volume, configuration, AI Search, and the Content API

Before you start

Access: you need a Conductor login to generate an API token. Not a Conductor user? Ask a Conductor admin to add you.
An inventory: list every legacy endpoint you call and where its output goes downstream (tables, dashboards, reports).
A parallel-run plan: keep the legacy connection running alongside the new one until the data matches, then cut over.

Migrate your integration

Switch authentication

Generate an API token in Conductor under Integrations > API > Create API Token. Copy it right away; the full token isn’t shown again. See Authentication for details.Then remove the signature logic and the apiKey/sig query parameters, and send the token in the Authorization header instead.

import hashlib, time, requests

def gen_api_sig(api_key, secret):
    m = hashlib.md5()
    m.update(api_key.encode())
    m.update(secret.encode())
    m.update(str(int(time.time())).encode())
    return m.hexdigest()

resp = requests.get(
    "https://api.conductor.com/v3/accounts",
    params={"apiKey": API_KEY, "sig": gen_api_sig(API_KEY, SECRET)},
)

import requests

HEADERS = {
    "Authorization": f"Bearer {CONDUCTOR_API_TOKEN}",
    "Content-Type": "application/json",
}

resp = requests.post(
    "https://api.conductor.com/data-api/v1/async/keyword_rankings",
    headers=HEADERS,
    json={...},  # endpoint-specific parameters
)

Store the token in a secrets manager or environment variable, not in your code.

Conductor’s API still accepts the legacy key + signature method during the transition (see Support for legacy connections). We recommend switching to a token now so you only migrate once.

Map your endpoints

Use this table to find the replacement for each legacy endpoint you call.

Legacy endpoint	Conductor’s API endpoint	Notes
`/v3/accounts`	`accounts_config`
`/v3/accounts/{accountId}/web-properties`	`web_properties_config` and `comparison_web_properties_config`	Comparison web properties are now a separate call.
`/v3/accounts/{accountId}/categories`	`keyword_search_config`	Use `config_type: "keyword_groups"`. Categories are now called keyword groups.
`/v3/accounts/{accountId}/web-properties/{webPropertyId}/tracked-searches`	`keyword_search_config`	Use `config_type: "keywords"`. Tracked searches are now called tracked keywords.
`/v3/rank-sources`	`keyword_search_config`	Use `config_type: "search_engines"`. Rank sources are now called search engines.
`/v3/locations`	`keyword_search_config`	Use `config_type: "locales"`. Locations are now called locales.
`/v3/devices`	`keyword_search_config`	Use `config_type: "devices"`.
`/v3/.../serp-items`	`keyword_rankings` or `highest_ranking_url_per_keyword`	Use `highest_ranking_url_per_keyword` if you only need each keyword’s top-ranking URL.
`/v3/.../search-volumes`	`keyword_rankings`	Set `includeMsv: true` to return the `approximate_search_volume` column.

Adopt the async query pattern

Every Data API and configuration endpoint is asynchronous. Instead of returning data immediately, each query follows a submit, poll, and paginate cycle:

Submit your query parameters. The API returns 202 Accepted with an executionId.
Poll by sending the executionId back to the same endpoint. You get 202 while the query runs and 200 with data when it’s COMPLETED.
Paginate by sending the executionId with the nextPageId from the previous response, one page at a time, until no nextPageId is returned.

import time, requests

URL = "https://api.conductor.com/data-api/v1/async/keyword_rankings"
HEADERS = {"Authorization": f"Bearer {CONDUCTOR_API_TOKEN}"}

def run_query(params, poll_interval=5):
    # 1. Submit
    execution_id = requests.post(URL, headers=HEADERS, json=params).json()["executionId"]

    pages, body = [], {"executionId": execution_id}
    while True:
        resp = requests.post(URL, headers=HEADERS, json=body)
        resp.raise_for_status()
        data = resp.json()

        # 2. Poll until the query completes
        if data.get("executionState") != "COMPLETED":
            time.sleep(poll_interval)
            continue

        pages.append(data)

        # 3. Paginate sequentially
        if not data.get("nextPageId"):
            return pages
        body = {"executionId": execution_id, "nextPageId": data["nextPageId"]}
        time.sleep(0.5)  # stay under 2 calls/second

See Async Queries for the full walkthrough.

Update your date logic

Conductor’s API doesn’t use timePeriodId or CURRENT. Instead, you send an explicit date range that lines up with the endpoint’s collection_frequency:

`collection_frequency`	Start date	End date
`WEEKLY`	A Sunday	A Saturday
`MONTHLY`	The first day of a month	The last day of a month

Requests with misaligned dates are rejected before the query runs. For example, a WEEKLY request with start_date: "2026-10-05" (a Monday) fails.To reproduce the legacy CURRENT time period, compute the most recent complete week:

from datetime import date, timedelta

def last_complete_week(today=None):
    today = today or date.today()
    # Saturday on or before yesterday
    end = today - timedelta(days=(today.weekday() + 2) % 7 or 7)
    start = end - timedelta(days=6)  # the Sunday before
    return start.isoformat(), end.isoformat()

Supported frequencies, maximum date ranges, and date field names vary by endpoint. Check each endpoint’s reference page before you build your requests.

Update parsing and storage

Legacy responses were named JSON objects. Conductor’s API returns two pieces instead: a schema array listing each column’s name and type in order, and results, a list of positional rows.

{
  "executionState": "COMPLETED",
  "schema": [
    { "name": "keyword", "type": "STRING" },
    { "name": "rank", "type": "INTEGER" }
  ],
  "results": [
    ["running shoes", "3"],
    ["trail shoes", "7"]
  ]
}

Build your rows from schema rather than hard-coding field positions. This snippet turns a completed response into a pandas DataFrame:

import pandas as pd

def to_dataframe(pages):
    columns = [col["name"] for col in pages[0]["schema"]]
    rows = [row for page in pages for row in page["results"]]
    return pd.DataFrame(rows, columns=columns)

If you load the data into a warehouse:

Remap your table columns to the new column names.
Upsert on the new identifiers rather than the legacy IDs.
Cast values to the types in schema. Some endpoints return all values as strings.

Budget for rate limits

Limits are the same as before: 5,000 calls per day and 2 calls per second per key. What changes is how many calls a job takes, because every poll and every page counts.The number of calls depends on how many keywords you track. Each keyword returns roughly 30 to 40 rows, and each page holds up to 1,000 rows. For example, a web property with 100 keywords returns about 100 × 40 = 4,000 rows, which is 4,000 ÷ 1,000 = 4 calls to retrieve the data. A weekly sync across 10 web properties of this size takes roughly 10 × 4 = 40 calls.Use a polling interval of a few seconds rather than polling continuously.See Rate Limits for details.

Validate and cut over

Run the legacy and new connections side by side for one or two collection cycles, then compare:

Ranks for a sample of keywords
Comparison web properties

Note that row counts will not match across legacy and new API calls. The legacy endpoint returned only your ranks and your competitors’ ranks, while the new endpoint returns all ranking results for each keyword. To compare like for like, filter the new results down to your web property and its comparison web properties first.

Data rounding and freshness are unchanged, so the numbers should match. Once they do:

Point your downstream dashboards and reports at the new data.
Turn off the legacy connection.
Revoke the legacy API key and secret in Conductor.

Tool-specific notes

conductor-api Python package: this package works only with the legacy API, and no updated version is planned. Replace it with direct HTTP requests, as shown in the examples above.
Domo and Looker Studio: update the connector’s authentication and endpoints. See Integrate Domo with the Conductor API.
No-code tools: if you use n8n, Zapier, or a similar tool, see Conductor’s API for non-developers.

Take advantage of what’s new

Once you’ve migrated, the same token gives you access to:

AI Search data: track how your brand appears in AI engines with brands, citations, sentiments, responses, and query fan-out.
The Content API: create drafts, generate insights, and score content inside your own workflows. See the Content API guide.

Troubleshooting and FAQ

I get a 401 Unauthorized after switching

Check that the header is formatted exactly as Authorization: Bearer YOUR_TOKEN and that the token hasn’t been revoked. If you’re unsure, generate a new token.

My request is rejected because of the date range

Your dates don’t line up with collection_frequency. Weekly ranges must run Sunday through Saturday; monthly ranges must run from the first to the last day of a month.

I'm getting 429 Too Many Requests

You’re polling too fast or have used up your daily limit. Increase your polling interval and see Rate Limits.

My numbers don't match the legacy data

Data rounding and freshness haven’t changed, so differences usually come from the request itself. Confirm you’re querying the same accounts, web properties, search engines, locales, devices, and date range in both connections.

Can I keep using my API key and secret?

Conductor’s API still accepts the key + signature method during the transition, but we recommend switching to an API token. The legacy /v3/... endpoints stop working on January 15, 2027, regardless of how you authenticate.

What happens on January 15, 2027?

The legacy Reporting API reaches end of life, and calls to the /v3/... endpoints fail. Any integration still using them will stop returning data.

Get help

Questions about your migration? Email [email protected].

​Overview

​Key dates

​Why migrate now

​Who needs to act

​What’s different at a glance

​Before you start

​Migrate your integration

​Tool-specific notes

​Take advantage of what’s new

​Troubleshooting and FAQ

​Get help

Overview

Key dates

Why migrate now

Who needs to act

What’s different at a glance

Before you start

Migrate your integration

Tool-specific notes

Take advantage of what’s new

Troubleshooting and FAQ

Get help