API Reference

Standard REST API over HTTPS. JSON responses. Works with Python, R, JavaScript, and any HTTP client.

Base URL

https://api.aucalia.com/v1

Authentication

All API requests require an API key passed in the Authorization header. You will receive your API key when your beta access is activated.

request header

Authorization: Bearer YOUR_API_KEY

Endpoints

GET /events

Retrieve government events with optional filters. Returns events cross-referenced with market data.

Parameter	Type	Description
ticker	string optional	Filter by stock ticker (e.g., `AAPL`)
source	string optional	Filter by government source (e.g., `sec_edgar`, `fda`)
event_type	string optional	Filter by event type (e.g., `8k_filing`, `drug_approval`)
date_from	date optional	Start date (YYYY-MM-DD)
date_to	date optional	End date (YYYY-MM-DD)
min_volume_spike	float optional	Minimum volume spike multiplier (e.g., `5.0`)
limit	int optional	Max results (default: 100, max: 1000)
offset	int optional	Pagination offset

GET /events/{event_id}

Retrieve a single event by its unique ID, including full market impact data and direct link to the government source.

GET /sources

List all available government data sources, their status, last update time, and total event count.

GET /tickers/{ticker}/summary

Get a summary of all government events for a specific ticker, including event counts by source and aggregate statistics.

GET /export

Bulk export events as CSV. Same filters as /events. Designed for backtesting and offline analysis.

Example Response

GET /events?ticker=ACME&source=sec_edgar

{
  "data": [
    {
      "event_id": "evt_8k_20251114_ACME",
      "ticker": "ACME",
      "event_date": "2025-11-14",
      "source": "sec_edgar",
      "event_type": "8k_filing",
      "description": "CEO Resignation",
      "source_url": "https://sec.gov/...",
      "market_impact": {
        "volume_spike": 12.4,
        "return_1d": "+3.21%",
        "return_5d": "+8.52%",
        "return_20d": "-3.21%",
        "vwap_deviation": 2.87
      }
    }
  ],
  "total": 47,
  "limit": 100,
  "offset": 0
}

Rate Limits

Beta accounts: 100 requests/minute. Bulk export requests count as 10 requests. Rate limit headers are included in every response.

Errors

The API uses standard HTTP status codes:

error response

{
  "error": "Invalid ticker symbol",
  "code": 400
}