Windsor.ai Connectors API Documentation

Overview

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.

Getting Started

Authentication

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

Base URL

The base URL for all API requests is:

https://connectors.windsor.ai

Making API Requests

Basic Request Structure

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

Required Parameters

Every API request must include these parameters:

Optional Parameters

You can customize your data request with these optional parameters:

Date Filtering

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}

Available date presets:

• today
• yesterday
• last_7d (Last 7 days)
• last_30d (Last 30 days)
• last_90d (Last 90 days)
• last_month (Previous calendar month)
• last_year (Previous calendar year)

Data Filtering

You can filter data using the filter parameter with expressions. The filter syntax uses field names with operators connected by special characters:

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

Filter Operators

Combining Filters

You can combine multiple filters using *$and* and *$or* operators:

https://connectors.windsor.ai/facebook?fields=date,campaign,spend&filter=campaign_$contains.Sale*$and*spend_$gt.100&api_key={your_api_key}

For complex filters with multiple conditions:

https://connectors.windsor.ai/googleanalytics4?fields=date,event_name,date_hour&filter=event_name_$eq.solicitud_depositada_usuario_nuevo*$and*date_hour_$neq.(other)*$and*date_hour_$neq.(not set)&api_key={your_api_key}

This example filters for:

1. Events named “solicitud_depositada_usuario_nuevo” AND
2. Where date_hour is not “(other)” AND
3. Where date_hour is not “(not set)”

Data Aggregation

You can aggregate data by time periods 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

Discovering Available Connectors and Fields

Listing All Connectors

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.

Retrieving Available Fields

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.

Supported Connectors

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.

Field Types

Fields returned by the API can have the following types:

Response Format

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
  }
}

Error Handling

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:

Rate Limits

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.

Renderers

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.

Example Use Cases

Retrieving Campaign Performance

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

Comparing Multiple Platforms

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

Getting E-commerce Conversion Data

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

Best Practices

1. Request Only Needed Fields: Limit your requests to only the fields you need to improve performance.

2. Use Date Presets: When possible, use date presets instead of custom date ranges for better caching.

3. Implement Caching: Cache API responses on your end to reduce the number of requests.

4. Handle Pagination: For large datasets, use the limit and offset parameters to paginate through results.

5. Error Handling: Implement proper error handling in your application to gracefully handle API errors.

User Agent

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.

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.

Changelog

2025-04-02

• Added information about different renderers

2025-03-18

• Added information about user agent

2025-03-17

• Initial API documentation release