TraceAlpha API Documentation

Programmatic Access to Alternative Data Signals & Stats

Back to Terminal

Interactive OpenAPI & Swagger Specifications

View the complete OpenAPI v3 specifications or try out API endpoints interactively in our sandbox playground.

Open Swagger Playgrounds View OpenAPI JSON Spec

Authentication

Protected premium endpoints support two alternative authentication mechanisms:

Developer API Access: Provide your premium API key in the Authorization header as a Bearer token:
Authorization: Bearer sk_live_tracealpha_...
Dashboard UI Access: A secure, HTTP-Only session cookie named tracealpha_api_key. This is set automatically on successful passwordless magic login and handled by your browser.

GET /api/signals

Retrieve extracted alternative data signals.

// Example Request

curl -X GET "https://tracealpha.io/api/signals?limit=10&ticker=AAPL" \

-H "Authorization: Bearer sk_live_tracealpha_12345"

Query Parameters

Parameter	Type	Description
`q`	string	Search text within the impact summary
`type`	string	Filter by event type (e.g., "Supply Chain Disruption")
`ticker`	string	Filter by company ticker
`figi`	string	Filter by Composite FIGI
`company`	string	Filter by company name
`sector`	string	Filter by industry sector
`sentiment`	number	Filter by exact sentiment score (-1.0 to 1.0)
`start_date`	string	Filter signals processed on or after this date (ISO 8601)
`end_date`	string	Filter signals processed on or before this date (ISO 8601)
`order`	string	Sort order by processed_at: `desc` (default) or `asc`
`page`	integer	Page number for pagination (default: 1)
`limit`	integer	Number of results per page (default: 10)

GET /api/sentiment-summary

Retrieve rolled-up company sentiment and momentum statistics.

Tier Differentiation Limits:

Premium Tier: Returns full floating-point precision of quantitative metrics (`weighted_sentiment`, `average_sentiment`) and unrestricted access to all paginated company index listings.
Free/Unauthenticated Tier:
- Global/bulk queries without company filtering are truncated to only the **top 3 teaser entities** (sorted by sentiment) with `requires_premium: true`.
- Company-specific queries (with `figi` or `ticker`) redact raw quantitative sentiment scores (`weighted_sentiment: null`, `average_sentiment: null`) and inject `premium_locked: true`.

// Example Request (Authenticated)

curl -X GET "https://tracealpha.io/api/sentiment-summary?ticker=NEE" \

-H "Authorization: Bearer sk_live_tracealpha_12345"

Query Parameters

Parameter	Type	Description
`ticker`	string	Filter by company ticker
`figi`	string	Filter by Composite FIGI
`sector`	string	Filter by industry sector
`sort`	string	Column to sort by (e.g. `weighted_sentiment`, `ticker`, `total_signals`)
`order`	string	Sort order: `desc` (default) or `asc`
`page`	integer	Page number for pagination (default: 1)
`limit`	integer	Number of results per page (default: 10)

Response Example (Premium Tier)

{
  "success": true,
  "authorized": true,
  "requires_premium": false,
  "data": [
    {
      "entity_figi": "BBG000BJSBJ0",
      "ticker": "NEE",
      "company_name": "NEXTERA ENERGY INC",
      "sector": "Infrastructure",
      "total_signals": 12,
      "average_sentiment": 0.35,
      "average_materiality": 3.4,
      "weighted_sentiment": 0.58,
      "bullish_signals_count": 8,
      "bearish_signals_count": 2,
      "neutral_signals_count": 2,
      "premium_locked": false
    }
  ],
  "total": 1,
  "page": 1,
  "has_more": false
}

Response Example (Free Tier - Redacted)

{
  "success": true,
  "authorized": false,
  "requires_premium": false,
  "data": [
    {
      "entity_figi": "BBG000BJSBJ0",
      "ticker": "NEE",
      "company_name": "NEXTERA ENERGY INC",
      "sector": "Infrastructure",
      "total_signals": 12,
      "average_sentiment": null,
      "average_materiality": 3.4,
      "weighted_sentiment": null,
      "bullish_signals_count": 8,
      "bearish_signals_count": 2,
      "neutral_signals_count": 2,
      "premium_locked": true
    }
  ],
  "total": 1,
  "page": 1,
  "has_more": false
}

GET /api/stats

Retrieve aggregate statistics for the dashboard.

// Example Request (Authenticated)

curl -X GET "https://tracealpha.io/api/stats" \

-H "Authorization: Bearer sk_live_tracealpha_12345"

Response Schema

{
  "totalEntities": 150,
  "totalSignals": 342,
  "sectorStats": {
    "Technology": 120,
    "Healthcare": 85,
    "Energy": 137
  }
}

GET /api/jobs

Retrieve historical and current scraping / ingestion task status records.

// Example Request

curl -X GET "https://tracealpha.io/api/jobs"

Response Schema

{
  "success": true,
  "data": [
    {
      "id": "a908bd16-ff2e-4bda-91ca-82ab78b30a54",
      "job_name": "fetch-sources-signals-job",
      "status": "success",
      "started_at": "2026-06-07T10:00:00.123456Z",
      "completed_at": "2026-06-07T10:04:12.789123Z",
      "processed_records": 12,
      "error_message": null
    }
  ]
}

Managed Entities API (Premium)

Retrieve and expand alternative data entity tracking coverage.

The entities endpoints allow premium developers to programmatically view the list of corporate entities under active surveillance, or request automatic resolution and addition of a new entity via Google Search Grounding and OpenFIGI identifiers.

GET/api/entities

Search tracked corporate entities

// Retrieve entities matching a search query

curl -X GET "https://tracealpha.io/api/entities?q=Tesla" \

-H "Authorization: Bearer sk_live_tracealpha_12345"

Query Parameters

Parameter	Type	Description
`q`	string	Optional search string filtering by company name, ticker, exchange, FIGI or sector (case-insensitive partial match).

Response Example

{
  "success": true,
  "data": [
    {
      "id": "e4b3c2a1-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
      "company_name": "Tesla, Inc.",
      "ticker": "TSLA",
      "exchange": "NASDAQ",
      "composite_figi": "BBG000N9MNX3",
      "sector": "Automotive / Clean Energy",
      "created_at": "2026-06-10T10:40:00.000Z",
      "updated_at": "2026-06-10T10:40:00.000Z"
    }
  ]
}

POST/api/entities

Expand entity tracking coverage (AI Grounded)

// Request addition of a new company by name

curl -X POST "https://tracealpha.io/api/entities" \

-H "Content-Type: application/json" \

-H "Authorization: Bearer sk_live_tracealpha_12345" \

-d '{"name": "Shopify"}'

Request Body

{
  "name": "Shopify"
}

Responses & Errors

Status Code	Description / Payload Reason
`200 OK`	Entity added successfully. Returns the resolved entity record containing its OpenFIGI Composite FIGI, exchange, ticker, and AI-grounded sector.
`400 Bad Request`	Missing or empty `name` field.
`401 Unauthorized`	Missing/invalid token, or session inactive.
`409 Conflict`	Company already exists. Triggered if the name matches, the resolved FIGI matches, or the resolved ticker + exchange matches.
`422 Unprocessable Entity`	Search grounding or OpenFIGI mapping could not resolve basic company fields or retrieve a valid Bloomberg Composite FIGI.
`502 Bad Gateway`	Failed to retrieve search results from external Gemini search grounding APIs.

Premium Sources & Audit Trail APIs

Sources endpoints (managing global source templates and listing bespoke feeds) require authorization via a valid premium API Key. You can authenticate either programmatically by passing the key in the Authorization: Bearer header, or via the secure session cookie tracealpha_api_key when using the dashboard console. Creating new global templates writes dynamic audit trail records to the database.

GET/api/sources

List all global templates or bespoke feeds. Use the query parameter is_global=true to filter for template indexes.

POST/api/sources

Create a new global template. Requires a JSON body payload containing: source_url (must include {company_name} or {ticker} placeholders), source_type, description, and is_global=true.

GET/api/admin/audit-logs

Query the complete history of administrative curation actions with delta payloads.