HEADLESS RECORDS DOCS

Quickstart: Add source-backed insider activity to a finance agent

Headless Records gives finance-agent builders a compact way to request public Form 4 insider activity for a ticker, verify freshness, carry caveats forward, and cite source filings.

First endpoint to call

Start with GET /v1/insider-activity/{ticker}/assessment. It returns the summary, freshness status, caveats, source references, and request metadata your agent needs for a bounded watched ticker universe.

Request

curl 'https://api.headlessrecords.dev/v1/insider-activity/TSLA/assessment?period=90d&freshness_window_hours=24' \
  -H 'X-API-Key: hr_live_REPLACE_ME'

Canonical response

{
  "request_id": "req_example_assessment",
  "api_version": "v1",
  "generated_at": "2026-05-21T12:00:00Z",
  "data_as_of": "2026-05-20T00:00:00Z",
  "ticker": "TSLA",
  "period": "90d",
  "freshness": {
    "freshness_window_hours": 24,
    "status": "degraded",
    "last_attempted_sync_at": "2026-05-21T11:40:00Z",
    "last_completed_sync_at": "2026-05-21T11:45:00Z",
    "last_successful_sync_at": "2026-05-20T11:45:00Z",
    "last_status": "completed_with_errors"
  },
  "assessment": {
    "activity_level": "moderate",
    "dominant_activity": "sales",
    "data_quality": "degraded",
    "summary_text": "Reported insider activity was moderate during the selected period, with sales as the dominant reported activity. Data quality is degraded."
  },
  "summary": {
    "transaction_count": 3,
    "sale_transaction_count": 3,
    "purchase_transaction_count": 0,
    "other_transaction_count": 0,
    "missing_price_count": 0,
    "missing_share_count": 0,
    "filing_count": 1,
    "filings_with_source_provenance_count": 1
  },
  "caveats": [
    {
      "code": "freshness_degraded",
      "severity": "warning",
      "message": "The latest SEC Form 4 sync completed with errors, so freshness is degraded."
    },
    {
      "code": "form4_amendments_excluded",
      "severity": "warning",
      "message": "Form 4/A amendments are currently excluded until amendment semantics are implemented."
    },
    {
      "code": "period_limited",
      "severity": "info",
      "message": "This assessment covers only the selected period."
    },
    {
      "code": "scheduled_plan_context_not_extracted",
      "severity": "info",
      "message": "This assessment does not currently extract or classify 10b5-1 or other scheduled-plan context."
    },
    {
      "code": "limited_insider_role_context",
      "severity": "info",
      "message": "Insider role context is limited to relationship fields present in imported filings."
    },
    {
      "code": "limited_watchlist_coverage",
      "severity": "info",
      "message": "Coverage is bounded to the configured enabled watchlist and imported public filing data."
    },
    {
      "code": "insider_activity_not_necessarily_predictive",
      "severity": "info",
      "message": "Reported insider activity is not necessarily predictive because transactions may have scheduled, tax, compensation, diversification, or other context."
    },
    {
      "code": "not_financial_advice",
      "severity": "info",
      "message": "This response summarizes public filing data and is not financial advice."
    }
  ],
  "methodology": {
    "version": "2026-05-11",
    "name": "insider_activity_assessment_v1",
    "description": "Summarizes reported insider filing activity using deterministic, non-advisory rules.",
    "rules": [
      "Counts imported SEC Form 4 transactions during the selected period.",
      "Classifies reported acquisition and disposition codes into descriptive activity counts.",
      "Reports freshness, caveats, methodology, and source provenance so agents can preserve context."
    ]
  },
  "sources": [
    {
      "accession_number": "0000001318-26-000123",
      "filing_date": "2026-05-20",
      "provenance_status": "available",
      "source_document_url": "https://www.sec.gov/Archives/edgar/data/1318605/000000131826000123/primary_doc.xml",
      "source_metadata_url": "https://data.sec.gov/submissions/CIK0001318605.json",
      "retrieved_at": "2026-05-20T18:00:00Z",
      "content_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

How to interpret the response

  • freshness.status tells your workflow whether the watched ticker data is fresh, stale, degraded, failed, or not yet synced.
  • caveats should be preserved in the agent response or used to constrain what the agent says.
  • sources gives accession numbers and provenance fields so your product can cite the filing-level source.
  • Do not infer future stock performance, investment merit, intent, or price movement from public filing activity.

Good vs bad agent output

Good

Recent public Form 4 filings show reported insider activity for TSLA. Headless Records marks the data degraded and includes caveats explaining why. This summarizes public filing activity only and is not investment advice.

Bad

Insiders are dumping shares, so the stock is likely to fall.