API Documentation

The @Filter Signals API provides programmatic access to real-time content filtering intelligence. All endpoints require authentication via API key.

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://atfilter.com/api/v1/signals/top-keywords?window=24h

API keys are issued when you subscribe. View plans or manage keys in your account.

Base URL

https://atfilter.com/api/v1/signals

OpenAPI 3.1 spec available at /api/v1/openapi

Rate Limits

Requests are rate-limited per subscription. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Observer

req/min

Analyst

120

req/min

Professional

300

req/min

Endpoints

7 RESTful JSON endpoints. OpenAPI 3.1 spec at /api/v1/openapi

Endpoint	Method	Path	Min. Tier
Top Keywords	GET	`/api/v1/signals/top-keywords`	Observer+
Keyword Timeseries	GET	`/api/v1/signals/keyword-timeseries`	Observer+
Domain Timeseries	GET	`/api/v1/signals/domain-timeseries`	Observer+
Geo Heat Map	GET	`/api/v1/signals/geo-heat`	Observer+
Trending Detection	GET	`/api/v1/signals/trending`	Observer+
Keyword Activity	GET	`/api/v1/signals/keyword-activity`	Observer+
Flexible Query	POST	`/api/v1/signals/query`	Analyst+

Endpoint Details

GET/api/v1/signals/top-keywordsObserver+

Returns the most suppressed keywords globally, ranked by total suppression count.

Parameters

windowTime window. Options: 1h, 6h, 12h, 24h, 7d, 30d (default: 24h)

limitMax results (1-500) (default: 50)

Response

{
  "window": "24h",
  "keywords": [
    {
      "keyword_raw": "trump",
      "suppressions": 14302,
      "users_est": 892,
      "rank": 1
    }
  ],
  "disclaimer": "Data reflects anonymous, aggregated user filtering behavior..."
}

GET/api/v1/signals/keyword-timeseriesObserver+

Returns suppression counts for a specific keyword over time, bucketed by hour, day, or week.

Parameters

keywordrequiredThe keyword to query

windowTime window. Options: 24h, 7d, 30d, 90d (default: 7d)

bucketAggregation bucket. Options: hour, day, week (default: hour)

Response

{
  "keyword": "trump",
  "window": "7d",
  "bucket": "hour",
  "timeseries": [
    {
      "ts": "2026-02-15T00:00:00Z",
      "suppressions": 421,
      "users_est": 89,
      "events": 312
    }
  ],
  "disclaimer": "Data reflects anonymous, aggregated user filtering behavior..."
}

GET/api/v1/signals/geo-heatObserver+

Returns geographic distribution of all suppression activity, aggregated by country, region, county, or city.

Parameters

windowTime window. Options: 1h, 6h, 12h, 24h, 7d, 30d (default: 24h)

levelGeographic resolution. Options: country, region, county, city (default: country)

Response

{
  "window": "24h",
  "level": "country",
  "regions": [
    {
      "geo_key": "US",
      "label": "US",
      "suppressions": 52100,
      "unique_users": 3200,
      "keyword_count": 47
    }
  ],
  "disclaimer": "Data reflects anonymous, aggregated user filtering behavior..."
}

GET/api/v1/signals/domain-timeseriesObserver+

Returns suppression activity for a specific domain over time.

Parameters

domainrequiredThe domain to query (e.g. cnn.com)

windowTime window. Options: 24h, 7d, 30d, 90d (default: 7d)

bucketAggregation bucket. Options: hour, day, week (default: hour)

Response

{
  "domain": "cnn.com",
  "window": "7d",
  "bucket": "day",
  "timeseries": [
    {
      "ts": "2026-02-15T00:00:00Z",
      "suppressions": 1832,
      "users_est": 412,
      "events": 1290
    }
  ],
  "disclaimer": "Data reflects anonymous, aggregated user filtering behavior..."
}

POST/api/v1/signals/queryAnalyst+

Flexible query endpoint. Filter and group by any combination of dimensions (keyword, domain, geography, time) in a single request.

Parameters

windowrequiredTime window. Options: 1h, 6h, 12h, 24h, 7d, 30d, 90d

filtersObject with dimension arrays: keywords, domains, platforms, page_contexts, countries, regions, counties, cities (max 50 values each)

group_byArray of dimensions to group by (max 5). Options: keyword, domain, platform, page_context, country, region, county, city, time (default: [] (totals only))

bucketAggregation bucket. Options: hour, day, week. Required when group_by includes "time"

order_byMeasure to sort by. Options: suppressions, unique_users, events (default: suppressions)

orderSort direction. Options: asc, desc (default: desc)

limitMax results (1-1000) (default: 100)

formatResponse format. Options: json, csv. CSV returns a downloadable file (default: json)

Example Request Body

{
  "window": "30d",
  "filters": {
    "keywords": ["trump", "voter fraud"],
    "domains": ["twitter.com", "facebook.com"],
    "countries": ["US"],
    "regions": ["US-PA"]
  },
  "group_by": ["keyword", "county", "time"],
  "bucket": "day",
  "order_by": "suppressions",
  "order": "desc",
  "limit": 100
}

Response

{
  "window": "30d",
  "bucket": "day",
  "group_by": ["keyword", "county", "time"],
  "results": [
    {
      "keyword": "trump",
      "county_id": "county_chester",
      "county_name": "Chester County",
      "ts": "2026-02-01T00:00:00Z",
      "suppressions": 1234,
      "unique_users": 56,
      "events": 890
    }
  ],
  "disclaimer": "Data reflects anonymous, aggregated user filtering behavior..."
}

GET/api/v1/signals/trendingObserver+

Detects keywords, domains, or other dimensions with the fastest growth rate by comparing recent activity to a baseline period.

Parameters

windowAnalysis window. Options: 24h, 7d, 30d. Determines the recent vs baseline comparison periods (default: 24h)

dimensionDimension to trend on. Options: keyword, domain, platform, page_context (default: keyword)

metricMetric to measure growth. Options: suppressions, events, unique_users (default: suppressions)

limitMax results (1-500) (default: 50)

min_baselineMinimum baseline value to include (filters out low-activity items) (default: 10)

Response

{
  "window": "24h",
  "dimension": "keyword",
  "metric": "suppressions",
  "recent_period": "6 hours",
  "baseline_period": "6 hours to 24 hours ago",
  "trending": [
    {
      "value": "immigration",
      "recent": 2451,
      "baseline": 890,
      "growth_pct": 175.4
    }
  ],
  "disclaimer": "Trending scores reflect relative growth in anonymous, aggregated filtering activity..."
}

GET/api/v1/signals/keyword-activityObserver+

Shows which keywords users are adding, removing, or editing in their filter lists. Reveals user intent and keyword churn.

Parameters

windowTime window. Options: 1h, 6h, 12h, 24h, 7d, 30d (default: 24h)

typeFilter by event type. Options: added, removed, edited, all (default: all)

limitMax results (1-500) (default: 50)

Response

{
  "window": "24h",
  "type": "all",
  "keywords": [
    {
      "keyword": "trump",
      "adds": 142,
      "removes": 23,
      "edits": 5,
      "total_events": 170,
      "unique_users": 134,
      "net_adds": 119
    }
  ],
  "disclaimer": "Data reflects anonymous, aggregated keyword configuration changes..."
}

Integration Tools

You don’t need to write code to use the API. These tools let you make requests and visualize results from a browser or spreadsheet.

Postman

Free

The easiest way to explore the API interactively.

Create a collection called “@Filter API”
In the collection’s Authorization tab, choose Bearer Token and paste your API key
Add a GET request for each endpoint (e.g. /top-keywords?window=7d&limit=20)
Use Environments to store your API key as a variable so you never hard-code it

postman.com

Google Sheets via Apipheny

$12/mo

Pull API data directly into Google Sheets cells. Supports both GET requests (Observer endpoints) and POST requests (Analyst /query endpoint).

Install Apipheny from the Google Workspace Marketplace
Open a sheet → Extensions → Apipheny → Import API
Set the URL, method, and add the header Authorization: Bearer YOUR_API_KEY
Click Run — data populates your sheet
Schedule auto-refresh (hourly/daily) to keep data current

Analyst tip: use "format": "csv" in POST body for clean tabular import.

More Google Sheets Connectors

SyncWithFree tier available. Google Sheets add-on with built-in hourly/daily auto-refresh scheduling. Supports POST with JSON body for the /query endpoint.

CoefficientFree / $49/mo. Custom API connector supporting POST + JSON body with scheduled refreshes.

Internal Dashboards

Build a live dashboard without writing a frontend using Retool or Appsmith:

Add a REST API data source with base URL https://atfilter.com/api/v1/signals
Set default header Authorization: Bearer YOUR_API_KEY
Drag in table and chart components, bind to queries

Ideal for sharing @Filter data with a team without distributing API keys.

MCP Server

Professional plan subscribers can use our MCP (Model Context Protocol) server to query the @Filter API using natural language through Claude Desktop, Cursor, or VS Code.

1. Get the MCP server

Install the @Filter MCP server globally via npm:

npm install -g @atfilter/mcp-server

Or clone the repository and build from source — see the GitHub README for details.

2. Configure your AI client

Claude Desktop

Edit your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "atfilter": {
      "command": "npx",
      "args": ["-y", "@atfilter/mcp-server"],
      "env": {
        "ATFILTER_API_KEY": "atf_your_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "atfilter": {
      "command": "npx",
      "args": ["-y", "@atfilter/mcp-server"],
      "env": {
        "ATFILTER_API_KEY": "atf_your_api_key_here"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "atfilter": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@atfilter/mcp-server"],
      "env": {
        "ATFILTER_API_KEY": "atf_your_api_key_here"
      }
    }
  }
}

Available Tools

The MCP server exposes 7 tools that your AI assistant can call:

Tool	Description
`signals_top_keywords`	Get the most suppressed keywords
`signals_keyword_timeseries`	Track a keyword’s activity over time
`signals_geo_heat`	Geographic distribution of filtering activity
`signals_domain_timeseries`	Track a domain’s filtering activity over time
`signals_trending`	Detect fastest-growing keywords, domains, platforms
`signals_keyword_activity`	See which keywords users are adding or removing
`signals_query`	Flexible multi-dimension query with any filter/group combination

Example Prompts

Once connected, ask your AI assistant things like:

›“What are the top 20 keywords being filtered right now?”
›“Show me the trend for 'immigration' over the past week”
›“Which domains have the most filtering activity in the US?”
›“What keywords are trending fastest in the last 24 hours?”
›“Which keywords are users adding to their filters most often today?”
›“Compare filtering activity on social media vs news sites in Pennsylvania this month”

Webhook Alerts

Configure webhook alerts to get notified when keywords or domains spike above a threshold. Manage your webhooks from your account page.

Webhook Payload

When a keyword or dimension exceeds your growth threshold, we POST a JSON payload to your configured URL:

{
  "source": "atfilter",
  "event": "trending_alert",
  "webhook_id": "clx...",
  "window": "24h",
  "dimension": "keyword",
  "threshold_pct": 100,
  "triggered_at": "2026-02-22T14:30:00.000Z",
  "alerts": [
    {
      "value": "immigration",
      "recent": 2451,
      "baseline": 890,
      "growth_pct": 175.4
    }
  ]
}

Dimensions: keyword, domain, platform, page_context

Windows: 24h, 7d, 30d

Cooldown: 15 min to 24 hours (prevents repeated alerts)

Limit: Up to 10 webhook alerts per subscription

Error Responses

400Invalid or missing parameter

401Missing or invalid API key

403Endpoint requires a higher plan tier

429Rate limit exceeded

500Internal server error

Data Disclaimer

@Map data represents collective user behavior patterns with statistical noise applied for privacy protection. Numbers are approximate and should not be cited as exact figures. @Filter makes no claims about the accuracy, completeness, or meaning of aggregated patterns.

Data reflects anonymous, aggregated user filtering behavior and does not represent editorial claims, endorsements, or factual assertions by @Filter or @Map.

Use of this API is subject to the API Terms of Service.

Need institutional access or custom endpoints? Contact us