Windsor.ai Connectors API Documentation

Windsor.ai Connectors provide a unified API to access data from over 300 marketing, analytics, and business platforms. This documentation will guide you through the process of using our API to retrieve data from various sources.

All API requests require an API key for authentication. You can obtain your API key from your Windsor.ai account. Please, keep in mind that your API key can’t be changed at the moment.

Include your API key in all requests using the api_key parameter:

https://connectors.windsor.ai/{connector}?api_key=your_api_key_here&fields=date,spend

The base URL for all API requests is:

https://connectors.windsor.ai

A basic API request follows this format:

https://connectors.windsor.ai/{connector}?fields={field1,field2,...}&api_key={your_api_key}

Where:

• {connector} is the name of the data source (e.g., facebook, googleanalytics4, linkedin)
• {field1,field2,...} is a comma-separated list of fields you want to retrieve
• {your_api_key} is your Windsor.ai API key

Every API request must include these parameters:

You can customize your data request with these optional parameters:

You can control how often recent data is refreshed from the upstream platform by using two parameters:refresh_since and refresh_interval.

This behaves the same way as our scheduled destination tasks (in databases and warehouse destinations), but is exposed publicly via the Connectors API.

All requests using these parameters remain subject to the global API rate limits.

How these parameters work:

1) refresh_since

• Default: 3d (currently, it supports only the last 3 days).
• Defines the recent time window that will be retrieved again from the upstream API.
• Data within this period is re-fetched according to refresh_interval.
• Data older than this period is considered stable and will be served from the cache if available.
• The global cache refresh interval doesn’t apply to this stable data.

2) refresh_interval

• Default: 6h.
• Defines how often data in the refresh_since window should be refreshed from the upstream API.
• The system will request new data from the source at most once every refresh_interval.
• This setting doesn’t affect the stable cache outside the refresh_since window.

Notes: 

The minimum allowed refresh_interval depends on your plan:

• STANDARD and PLUS plans can use refresh_interval=1h or more (e.g. 1h, 2h, 6h, …).;
• PROFFESIONAL and ENTERPRISE tiers can use refresh_interval=15min or more (e.g. 15min, 30min, 1h, …).

Example:

To refresh the last 3 days of Google Ads data at least once per hour:

https://connectors.windsor.ai/google_ads?api_key=API_KEY&fields=date,campaign,spend&refresh_since=3d&refresh_interval=1h

Python

import requests

API_KEY = "your_api_key_here"
connector = "facebook"
fields = "date,campaign,spend,impressions,clicks"

url = f"https://connectors.windsor.ai/{connector}?api_key={API_KEY}&fields={fields}"

response = requests.get(url)
print(response.json())

Javascript

const API_KEY = "your_api_key_here";
const connector = "facebook";
const fields = "date,campaign,spend,impressions,clicks";

const url = `https://connectors.windsor.ai/${connector}?api_key=${API_KEY}&fields=${fields}`;

fetch(url)
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("API error:", err));

You can specify date ranges in two ways:

1. Using date_preset:

   https://connectors.windsor.ai/facebook?fields=date,spend&date_preset=last_30d

2. Using date_from and date_to:

   https://connectors.windsor.ai/facebook?fields=date,spend&date_from=2023-01-01&date_to=2023-01-31&api_key={your_api_key}

Simple presets

• last_7d (last 7 days)
• last_30d (last 30 days)
• last_90d (last 90 days)
• last_year (previous calendar year)

General format
You can also use dynamic presets in the following formats:

• last_Xd last X days
• last_XdT last X days including today
• last_Xw last X weeks
• last_Xm last X months
• last_Xy last X years

Year based

• last_year previous calendar year
• last_yearT previous calendar year including today
• last_2years last 2 years
• last_2yearsT last 2 years including today

Current period

• this_month this month
• this_monthT this month including today
• this_year this year
• this_yearT this year including today

Examples

• last_7d
• last_30dT
• last_3m

Filters use a JSON array format for readability and grouping.

• Each condition is a list: [field, operator, value]
• Combine conditions with "and" / "or"
• Nest lists to group conditions

⚠️ Note: For actual API requests, URL-encode the filter parameter. The examples below are shown in plain JSON for readability.

• Single filter:

https://connectors.windsor.ai/facebook?fields=date,campaign,spend&filter=[["campaign","eq","Summer Sale"]]&api_key={your_api_key}

• Check for null values:

https://connectors.windsor.ai/facebook?fields=date,campaign,clicks&filter=[["clicks","null",null]]&api_key={your_api_key}

• Multiple conditions (AND):

https://connectors.windsor.ai/facebook?fields=date,spend&filter=[["spend","gt",100],"and",["campaign","contains","Sale"]]&api_key={your_api_key}

• Nested groups (AND + OR):

https://connectors.windsor.ai/facebook?fields=date,campaign,spend&filter=[[["campaign","eq","foobar"],"or",["spend","eq",10]],"and",["campaign","eq","abc (us)"]]&api_key={your_api_key}

import requests
import json

api_key = "your_api_key_here"
connector = "facebook"
fields = "date,campaign,spend"

# Use json.dumps to convert the filter array to JSON string
filter_query = json.dumps([["spend","gt",100],"and",["campaign","contains","Sale"]])

url = f"https://connectors.windsor.ai/{connector}?api_key={api_key}&fields={fields}&filter={filter_query}"
response = requests.get(url)
print(response.json())

Javascript

const apiKey = "your_api_key_here";
const connector = "facebook";
const fields = "date,campaign,spend";

// Convert the filter array to JSON string
const filterQuery = JSON.stringify([["spend","gt",100],"and",["campaign","contains","Sale"]]);

const url = `https://connectors.windsor.ai/${connector}?api_key=${apiKey}&fields=${fields}&filter=${filterQuery}`;

fetch(url)
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("API error:", err));

You can aggregate data by time using the date_aggregation parameter:

https://connectors.windsor.ai/facebook?fields=date,spend&date_aggregation=month&api_key={your_api_key}

Available aggregation periods:

• day (default)
• week
• month
• year

You can get a list of all available connectors by making a request to:

https://connectors.windsor.ai/list_connectors

This endpoint returns a JSON array of all connectors that are available through the Windsor.ai API.

To see what fields are available for a specific connector, use:

https://connectors.windsor.ai/{connector}/fields

For example, to get all available fields for Facebook:

https://connectors.windsor.ai/facebook/fields

When authenticated with your API key, this endpoint will also return any custom fields that have been configured for your account:

https://connectors.windsor.ai/facebook/fields?api_key={your_api_key}

The response includes detailed information about each field, including:

• Field ID (used in API requests)
• Field name (human-readable name)
• Field type (TEXT, NUMERIC, DATE, etc.)
• Field description

This information is essential for constructing effective API queries and understanding the data structure of each connector.

Some connectors support additional configuration options.

These options allow you to customise how data is pulled — such as selecting accounts, toggling breakdowns, choosing report types, or enabling advanced filtering.

This endpoint returns all available options for a specific connector.

Endpoint

https://connectors.windsor.ai/{connector}/options

Replace {connector} with the connector ID (e.g., facebook, hubspot, salesforce).

Example (Facebook Ads)

Request:

https://connectors.windsor.ai/facebook/options

Example response (simplified):

{ "fields": [ { "key": "account_id", "label": "Ad Account", "type": "dropdown", "required": true, "values": [ { "id": "1234567890", "name": "ACME Ads Account" }, { "id": "9876543210", "name": "Europe Ads Account" } ] }, { "key": "breakdowns", "label": "Breakdowns", "type": "multi_select", "required": false, "values": [ "age", "gender", "country", "placement" ] }, { "key": "level", "label": "Reporting Level", "type": "select", "required": false, "values": [ "ad", "adset", "campaign", "account" ] } ] }

Typical use cases:

• Build a UX for selecting Facebook Ad Accounts or Google Ads Customers
• Display available report types or breakdown options
• Validate user input when generating an authorisation or sync configuration
• Dynamically load options for any connector during onboarding

Windsor.ai supports over 300 connectors, including:

• Social Media: Facebook, Instagram, LinkedIn, Twitter, TikTok, Snapchat, Pinterest
• Search & Display: Google Ads, Microsoft Bing, Google Search Ads, DV360, CM360
• Analytics: Google Analytics 4, Adobe Analytics, Mixpanel, Amplitude
• CRM & Marketing: Salesforce, HubSpot, Marketo, Mailchimp
• E-commerce: Shopify, WooCommerce, Amazon, Stripe
• And many more…

For a complete list of connectors and their specific fields, please refer to our Connectors Directory.

Fields returned by the API can have the following types:

API responses are returned in JSON format:

{
  "data": [
    {
      "date": "2023-01-01",
      "spend": 125.45,
      "impressions": 10234,
      "clicks": 342
    },
    {
      "date": "2023-01-02",
      "spend": 134.67,
      "impressions": 11456,
      "clicks": 389
    }
  ],
  "meta": {
    "total_count": 31,
    "returned_count": 2
  }
}

When an error occurs, the API will return an appropriate HTTP status code and a JSON response with error details:

{
  "error": {
    "code": "authentication_error",
    "message": "Invalid API key provided"
  }
}

Common error codes:

API requests are subject to rate limits to ensure fair usage. The current rate limits are:

• 600 requests per minute
• 10,000 requests per day

If you exceed these limits, you’ll receive a 429 status code. The response will include headers indicating your remaining quota and when it will reset.

The _renderer parameter specifies the format of the data returned by the Windsor.ai API. Available options include:

• JSON: returns data in JSON format, ideal for web applications and integrations.

  https://connectors.windsor.ai/googleanalytics4?api_key=your_api_key&fields=date,spend&_renderer=json

• CSV: returns data in CSV format, suitable for spreadsheets and data analysis.

  https://connectors.windsor.ai/googleanalytics4?api_key=your_api_key&fields=date,spend&_renderer=csv

• Google Sheets: directly imports data into Google Sheets.

  https://connectors.windsor.ai/googleanalytics4?api_key=your_api_key&fields=date,spend&_renderer=googlesheets

Default: If no _renderer is specified, the API returns JSON format by default.

Windsor.ai provides an endpoint to generate a co-user authorisation link. This allows your clients or teammates to connect their data sources without sharing credentials.

You can restrict the link to a single connector or allow any source.

Use this endpoint if you want the user to authorise only one specific data source.

https://onboard.windsor.ai/api/team/generate-co-user-url/?allowed_sources={source}&api_key={API_KEY}

Example (LinkedIn Ads only):

https://onboard.windsor.ai/api/team/generate-co-user-url/?allowed_sources=linkedin&api_key=YOUR_API_KEY

This link allows the user to connect only the LinkedIn data source.

Use this endpoint if you want the user to connect any data source supported by Windsor.ai:

https://onboard.windsor.ai/api/team/generate-co-user-url?api_key={API_KEY}

Example:

https://onboard.windsor.ai/api/team/generate-co-user-url?api_key=YOUR_API_KEY

This link lets the user choose and authorise any available connector.

This endpoint returns all data source accounts connected to your Windsor.ai workspace.

You can query a specific datasource or request all accounts.

Endpoint:

https://onboard.windsor.ai/api/common/ds-accounts?datasource=all

Example response (simplified):

[ { "datasource": "google_ads", "account_name": "ACME Google Ads", "account_id": "123-456-7890", "status": "active" }, { "datasource": "facebook", "account_name": "ACME Facebook Ads", "account_id": "987654321", "status": "active" } ]

Endpoint:

https://onboard.windsor.ai/api/common/ds-accounts?datasource={SOURCE}

Example (Facebook Ads data source):

https://onboard.windsor.ai/api/common/ds-accounts?datasource=facebook

Returns only Facebook Ads accounts connected to the workspace.

This endpoint returns custom fields defined on your Windsor.ai workspace.

These fields can be used in queries or enrichments across supported data sources.

Endpoint:

https://onboard.windsor.ai/api/custom-fields

These fields are available immediately after creation and can be referenced in API queries.

https://connectors.windsor.ai/facebook?fields=date,campaign,spend,impressions,clicks&date_preset=last_30d&api_key={your_api_key}

https://connectors.windsor.ai/all?fields=date,source,spend,impressions,clicks&date_preset=last_30d&api_key={your_api_key}

https://connectors.windsor.ai/googleanalytics4?fields=date,campaign,transactions,revenue&date_preset=last_30d&api_key={your_api_key}

1. Request only needed fields
2. Use date presets when possible
3. Implement caching
4. Handle pagination with limit + offset
5. Always handle errors with care

When making API requests to Windsor.ai connectors, the system identifies itself using the following user agent:

Windsor/1.0

This user agent is automatically included in all API requests made through our official SDKs and libraries. If you’re building custom integrations or directly interacting with our API, we recommend including this user agent in your requests for better tracking and support.

If you encounter any issues or have questions about using our API, please contact our support team at [email protected] or visit our Help Center.

2025-11-13

• Creation of authorization links added

2025-04-02

• Added information about different renderers

2025-03-18

• Added information about the user agent

2025-03-17

• Initial API documentation release