API DOCUMENTATION

Public API v1 reference

Endpoints, parameters, and response structures for company fundamentals, supplemental datasets, earnings, and Congress trading analytics.

Base URLhttps://api.vizualstocks.com/v1

API key

Query Parameter?apikey=YOUR_API_KEY

Request HeaderX-API-Key: YOUR_API_KEY

ResponseJSON · ISO 8601 UTC

Jump to

GETTING STARTED

Make your first request

Add your API key to the request URL. Successful V1 responses use the direct endpoint-specific shapes shown below; errors use one shared flat object.

Add your API key

Append ?apikey=YOUR_API_KEY to the URL. The X-API-Key request header is also supported.

Choose an endpoint

Start with the company catalog, then use a ticker and stable metric ID to request data.

Handle the response

Read the endpoint-specific response directly. Authentication, validation, access and quota errors use the shared error shape.

First request

https://api.vizualstocks.com/v1/companies?search=PLTR&apikey=YOUR_API_KEY

Direct success response

200 OK

[
  {
    "ticker": "PLTR",
    "name": "Palantir Technologies Inc",
    "marketCap": 395785066250,
    "hasCompanyKpis": true,
    "hasSegments": true,
    "hasShortInterest": true,
    "hasRapidEarnings": true,
    "freeSandboxAvailable": true,
    "coverage": {
      "companyKpiCount": 17,
      "segmentMetricCount": 2,
      "activeMetricCount": 19,
      "discontinuedMetricCount": 0
    }
  }
]

Error envelope

4xx / 5xx

{
  "error": "invalid_api_key",
  "message": "The API key is invalid or has been revoked."
}

Public documentation, protected data

Examples are illustrative excerpts, not complete live datasets, and may use a different ticker or metric from a customized request. The Structure tab describes the full response contract. Interactive value-bearing requests require login and a valid API key.

CORE CONCEPTS

A stable contract for company data

Public identifiers and response models are independent from VizualStocks’ internal charting, storage, and collection classes.

COMPANIES

Flexible ticker input

Use aapl or AAPL—both work. Responses return uppercase tickers.

METRICS

Stable metric IDs

Every series uses a lower camelCase ID. Display labels may improve without changing the public identifier.

CLASSIFICATION

KPIs versus segments

companyKpi covers operating measures. segment covers business, product, geography, or platform breakdowns.

LIFECYCLE

History stays durable

A discontinued metric remains queryable; it means the issuer stopped reporting it, not that its history was deleted.

PERIODS

Issuer identity plus chart labels

normalizedPeriod is the VizualStocks chart label; fiscal year, quarter, and period end retain issuer reporting identity.

VALUES

Base-unit numbers

Values are JSON numbers in normalized base units. Missing single-series points are omitted; flat multi-metric rows use null.

MONETARY VALUES

Currency versus counts

isMonetary identifies currency amounts; false means a count, unit, percentage, or ratio. Use this flag, not valueFormat: "number", to decide whether a value represents money.

PERCENTAGES

The scale is explicit

Read valueFormat: percentageFraction means 0.3 is 30%; percentageUnits means 30 is 30%. Set percentageFormat=fraction or percentageFormat=units for a consistent scale. By default, uniform histories keep their scale and mixed histories use fractions; percentageFormat=stored returns original scales.

DISPLAY & CONVERSION

Keep the value, choose the display

Use isMonetary and reportingCurrency for currency conversion; null means the reporting currency is unavailable. Format display units in your app—for example, 1,250,000 as 1.25M.

SOURCES

Optional, incremental evidence

Add includeSources=true for reviewed issuer references. Source metadata appears only where verified references are available; values are returned either way.

PLAN ACCESS

Discover everything, then expand access

All plans can browse the full directories; freeSandboxAvailable marks sandbox access. Free Sandbox includes 20 companies, five curated metrics each, their supplemental data, five Congress members, and full available history. Upgrade for broader coverage without changing endpoints, API keys, or response formats.

CONGRESS MODELS

Calculated portfolios, not trade feeds

Congress endpoints return calculated holdings and performance estimates, not raw trades or disclosures. Responses identify whether results cover the curated sandbox members or the full modeled universe.

ENDPOINT REFERENCE

List companies

Discover the full supported-company universe and identify which companies are available in Free Sandbox before requesting their datasets.

GET/v1/companies

PARAMETERS5

0 required · 5 optional

searchstringOptional

Match a ticker or company name.

Query parameter

hasCompanyKpisbooleanOptional

Filter by company-KPI coverage.

Query parameter

hasSegmentsbooleanOptional

Filter by segment coverage.

Query parameter

pageintegerOptional

1-indexed page number. Supply together with pageSize to opt in to pagination.

Query parameter

pageSizeintegerOptional

Positive page size. Supply together with page; no page size is inferred or capped.

Query parameter

Freshness & caching

60-second private cache. Omit pagination for the full filtered catalog; plan limits apply to data requests, not discovery.

REQUEST

https://api.vizualstocks.com/v1/companies?apikey=YOUR_API_KEY

RESPONSE

200 OK

[
  {
    "ticker": "PLTR",
    "name": "Palantir Technologies Inc",
    "marketCap": 395785066250,
    "hasCompanyKpis": true,
    "hasSegments": true,
    "hasShortInterest": true,
    "hasRapidEarnings": true,
    "freeSandboxAvailable": true,
    "coverage": {
      "companyKpiCount": 17,
      "segmentMetricCount": 2,
      "activeMetricCount": 19,
      "discontinuedMetricCount": 0
    }
  },
  {
    "ticker": "TSLA",
    "name": "Tesla Inc",
    "marketCap": 1100000000000,
    "hasCompanyKpis": true,
    "hasSegments": true,
    "hasShortInterest": true,
    "hasRapidEarnings": true,
    "freeSandboxAvailable": true,
    "coverage": {
      "companyKpiCount": 31,
      "segmentMetricCount": 21,
      "activeMetricCount": 45,
      "discontinuedMetricCount": 7
    }
  },
  {
    "ticker": "MU",
    "name": "Micron Technology Inc",
    "marketCap": 180000000000,
    "hasCompanyKpis": true,
    "hasSegments": true,
    "hasShortInterest": true,
    "hasRapidEarnings": true,
    "freeSandboxAvailable": true,
    "coverage": {
      "companyKpiCount": 1,
      "segmentMetricCount": 17,
      "activeMetricCount": 8,
      "discontinuedMetricCount": 10
    }
  },
  {
    "ticker": "MSFT",
    "name": "Microsoft Corp",
    "marketCap": 3700000000000,
    "hasCompanyKpis": true,
    "hasSegments": true,
    "hasShortInterest": true,
    "hasRapidEarnings": true,
    "freeSandboxAvailable": true,
    "coverage": {
      "companyKpiCount": 3,
      "segmentMetricCount": 23,
      "activeMetricCount": 22,
      "discontinuedMetricCount": 4
    }
  }
]

ENDPOINT REFERENCE

Retrieve the company metric catalog

Discover the stable public metric IDs and metadata available for one supported company without downloading history.

GET/v1/companies/{ticker}/metrics/catalog

PARAMETERS4

1 required · 3 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

statusactive | discontinued | allOptional

Lifecycle filter. Defaults to all.

Query parameter

typecompanyKpi | segment | allOptional

Metric classification. Defaults to all.

Query parameter

frequencyquarterly | annual | allOptional

Reporting frequency. Defaults to all.

Query parameter

Freshness & caching

60-second private cache. valueFormat gives the default scale; mixed series list period overrides (annual keys: YYYY). A plain percentage label is unclassified.

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/metrics/catalog?status=all&type=all&apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "PLTR",
  "reportingCurrency": "USD",
  "metrics": [
    {
      "metricId": "customerCount",
      "name": "Customer Count",
      "description": "Total customers at the end of the period.",
      "type": "companyKpi",
      "status": "active",
      "frequencies": [
        "quarterly",
        "annual"
      ],
      "isMonetary": false,
      "valueFormat": "number",
      "firstReportedPeriod": "Q4'20",
      "lastReportedPeriod": "Q2'26",
      "discontinuation": null
    },
    {
      "metricId": "remainingPerformanceObligations",
      "name": "Remaining Performance Obligations",
      "description": "Contracted revenue not yet recognized at period end.",
      "type": "companyKpi",
      "status": "active",
      "frequencies": [
        "quarterly",
        "annual"
      ],
      "isMonetary": true,
      "valueFormat": "number",
      "firstReportedPeriod": "Q2'24",
      "lastReportedPeriod": "Q2'26",
      "discontinuation": null
    },
    {
      "metricId": "ruleOf40",
      "name": "Rule of 40",
      "description": "Revenue growth plus adjusted operating margin.",
      "type": "companyKpi",
      "status": "active",
      "frequencies": [
        "quarterly",
        "annual"
      ],
      "isMonetary": false,
      "valueFormat": "percentageUnits",
      "firstReportedPeriod": "Q2'24",
      "lastReportedPeriod": "Q2'26",
      "discontinuation": null
    },
    {
      "metricId": "netDollarRetention",
      "name": "Net Dollar Retention",
      "description": "Trailing customer revenue retained and expanded year over year.",
      "type": "companyKpi",
      "status": "active",
      "frequencies": [
        "quarterly",
        "annual"
      ],
      "isMonetary": false,
      "valueFormat": "percentageUnits",
      "firstReportedPeriod": "Q2'24",
      "lastReportedPeriod": "Q2'26",
      "discontinuation": null
    }
  ]
}

ENDPOINT REFERENCE

Retrieve metric history

Load normalized history for one stable company KPI or segment metric for a chart, model, or research workflow.

GET/v1/companies/{ticker}/metrics/{metricId}

PARAMETERS7

2 required · 5 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

metricIdstringRequired

Stable lower camel case public metric ID.

Path parameter

frequencyquarterly | annualOptional

Defaults to quarterly.

Query parameter

orderasc | descOptional

Observation order. Defaults to asc.

Query parameter

limitintegerOptional

Positive maximum observation count.

Query parameter

includeSourcesbooleanOptional

Defaults to false. When true, adds a verified source object to each covered observation.

Query parameter

percentageFormatstored | fraction | unitsOptional

Omit for original scale on uniform series and decimal fractions on mixed series. stored returns raw stored scale; fraction makes 0.3 mean 30%; units makes 30 mean 30%. Only percentage metrics change.

Query parameter

Freshness & caching

30-second private cache lifetime. percentageFormat sets the returned percentage scale; includeSources=true adds available reviewed citations.

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/metrics/customerCount?order=desc&includeSources=true&apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "PLTR",
  "reportingCurrency": "USD",
  "isMonetary": false,
  "valueFormat": "number",
  "data": [
    {
      "normalizedPeriod": "Q2'26",
      "fiscalYear": 2026,
      "fiscalQuarter": 2,
      "periodEnd": "2026-06-30",
      "value": 1049,
      "source": {
        "originalSourceUrl": "https://investors.palantir.com/files/Palantir - Q2 2026 Business Update.pdf",
        "archivedPdfUrl": "https://vizualstocksmedia.blob.core.windows.net/company-ingestion-documents/pltr/067c5ef76f971ec80999/b45d935d9fa8f93d47472937502104d69f422f317a6bc38fa8e746d4f8ccd5e1.pdf",
        "pageNumber": 24,
        "imageUrl": "https://vizualstocksmedia.blob.core.windows.net/company-ingestion-documents/pltr/067c5ef76f971ec80999/b45d935d9fa8f93d47472937502104d69f422f317a6bc38fa8e746d4f8ccd5e1-page-24.jpg",
        "locationDescription": "Page 24. issuer CustomerCount table/chart for Q2'26."
      }
    },
    {
      "normalizedPeriod": "Q1'26",
      "fiscalYear": 2026,
      "fiscalQuarter": 1,
      "periodEnd": "2026-03-31",
      "value": 1007
    },
    {
      "normalizedPeriod": "Q4'25",
      "fiscalYear": 2025,
      "fiscalQuarter": 4,
      "periodEnd": "2025-12-31",
      "value": 954
    },
    {
      "normalizedPeriod": "Q3'25",
      "fiscalYear": 2025,
      "fiscalQuarter": 3,
      "periodEnd": "2025-09-30",
      "value": 911
    },
    {
      "normalizedPeriod": "Q2'25",
      "fiscalYear": 2025,
      "fiscalQuarter": 2,
      "periodEnd": "2025-06-30",
      "value": 849
    }
  ]
}

ENDPOINT REFERENCE

Retrieve all company metrics

Populate KPI and segment dashboards with flat period rows, metric definitions, and explicit segment groupings in one request.

GET/v1/companies/{ticker}/metrics

PARAMETERS8

1 required · 7 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

statusactive | discontinued | allOptional

Series lifecycle. Defaults to all, so no lifecycle is omitted implicitly.

Query parameter

typecompanyKpi | segment | allOptional

Series classification. Defaults to all.

Query parameter

frequencyquarterly | annualOptional

Reporting frequency. Defaults to quarterly.

Query parameter

orderasc | descOptional

Reporting-period order. Defaults to asc.

Query parameter

limitintegerOptional

Positive maximum number of reporting periods.

Query parameter

includeSourcesbooleanOptional

Defaults to false. When true, adds verified source references without changing the flat data rows. Partial coverage returns only the available references.

Query parameter

percentageFormatstored | fraction | unitsOptional

Omit for original scale on uniform series and decimal fractions on mixed series. stored returns raw stored scale; fraction makes 0.3 mean 30%; units makes 30 mean 30%. Only percentage metrics change.

Query parameter

Freshness & caching

30-second private cache lifetime. Percentage conversion affects only percentage columns; includeSources=true adds available citations in sources[].

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/metrics?status=all&type=all&order=desc&apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "PLTR",
  "reportingCurrency": "USD",
  "data": [
    {
      "normalizedPeriod": "Q2'26",
      "fiscalYear": 2026,
      "fiscalQuarter": 2,
      "periodEnd": "2026-06-30",
      "commercialRevenue": 945000000,
      "customerCount": 1049,
      "governmentRevenue": 990000000
    },
    {
      "normalizedPeriod": "Q1'26",
      "fiscalYear": 2026,
      "fiscalQuarter": 1,
      "periodEnd": "2026-03-31",
      "commercialRevenue": 774000000,
      "customerCount": 1007,
      "governmentRevenue": 858000000
    }
  ],
  "metrics": [
    {
      "metricId": "commercialRevenue",
      "name": "Commercial Revenue",
      "description": "Revenue from commercial customers during the quarter.",
      "type": "segment",
      "status": "active",
      "isMonetary": true,
      "valueFormat": "number",
      "discontinuation": null
    },
    {
      "metricId": "customerCount",
      "name": "Customer Count",
      "description": "Total customers at the end of the period.",
      "type": "companyKpi",
      "status": "active",
      "isMonetary": false,
      "valueFormat": "number",
      "discontinuation": null
    },
    {
      "metricId": "governmentRevenue",
      "name": "Government Revenue",
      "description": "Revenue from government customers during the quarter.",
      "type": "segment",
      "status": "active",
      "isMonetary": true,
      "valueFormat": "number",
      "discontinuation": null
    }
  ],
  "segmentGroups": [
    {
      "groupId": "revenueBySegment",
      "title": "Revenue by Segment",
      "metricIds": [
        "commercialRevenue",
        "governmentRevenue"
      ]
    }
  ]
}

ENDPOINT REFERENCE

Retrieve short interest

Add historical settlement-based short-interest observations to a research product or customer-facing workflow.

GET/v1/companies/{ticker}/short-interest

PARAMETERS5

1 required · 4 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

fromdateOptional

Inclusive YYYY-MM-DD lower bound.

Query parameter

todateOptional

Inclusive YYYY-MM-DD upper bound.

Query parameter

orderasc | descOptional

Observation order. Defaults to asc.

Query parameter

limitintegerOptional

Positive maximum observation count.

Query parameter

Freshness & caching

Short interest is settlement-based rather than live daily data and uses a five-minute private cache lifetime.

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/short-interest?order=desc&apikey=YOUR_API_KEY

RESPONSE

200 OK

[
  {
    "settlementDate": "2026-07-31",
    "sharesShorted": 68066419,
    "sharesFloat": 2193497664,
    "shortInterestPercentage": 3.1
  },
  {
    "settlementDate": "2026-07-15",
    "sharesShorted": 77877652,
    "sharesFloat": 2193477000,
    "shortInterestPercentage": 3.55
  },
  {
    "settlementDate": "2026-06-30",
    "sharesShorted": 72549218,
    "sharesFloat": 2189964000,
    "shortInterestPercentage": 3.31
  },
  {
    "settlementDate": "2026-06-15",
    "sharesShorted": 70188405,
    "sharesFloat": 2187451000,
    "shortInterestPercentage": 3.21
  },
  {
    "settlementDate": "2026-05-29",
    "sharesShorted": 74621990,
    "sharesFloat": 2185338000,
    "shortInterestPercentage": 3.41
  }
]

ENDPOINT REFERENCE

Retrieve analyst estimate revision trends

Follow how analyst consensus revenue and normalized EPS expectations evolve for each target reporting period. Each observation captures the average analyst forecasts for revenue and EPS on its collected date, building a history of expectations for the same quarter or fiscal year.

GET/v1/companies/{ticker}/estimate-revisions

PARAMETERS5

1 required · 4 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

frequencyquarterly | annual | allOptional

Target-period frequency. Defaults to all.

Query parameter

normalizedPeriodstringOptional

Exact normalized chart period, such as Q3'26 or 2027.

Query parameter

orderasc | descOptional

History order within every target period. Defaults to asc.

Query parameter

limitintegerOptional

Positive maximum history points returned per target period.

Query parameter

Freshness & caching

Five-minute private cache. History is unlimited unless limit is requested; normalizedPeriod selects one chart period.

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/estimate-revisions?apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "PLTR",
  "reportingCurrency": "USD",
  "data": [
    {
      "frequency": "quarterly",
      "periods": [
        {
          "normalizedPeriod": "Q1'23",
          "periodEndDate": "2023-03-31",
          "history": [
            {
              "collectedDate": "2023-02-08",
              "revenueEstimate": 520450000,
              "epsEstimate": 0.04
            },
            {
              "collectedDate": "2023-02-10",
              "revenueEstimate": 520000000,
              "epsEstimate": 0.04
            },
            {
              "collectedDate": "2023-04-11",
              "revenueEstimate": 505600000,
              "epsEstimate": 0.04
            }
          ]
        }
      ]
    }
  ]
}

ENDPOINT REFERENCE

Retrieve historical ownership

Track observed institutional and insider ownership over time alongside VizualStocks' derived undisclosed remainder.

GET/v1/companies/{ticker}/ownership-history

PARAMETERS5

1 required · 4 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

fromdateOptional

Inclusive YYYY-MM-DD lower bound.

Query parameter

todateOptional

Inclusive YYYY-MM-DD upper bound.

Query parameter

orderasc | descOptional

Observation order. Defaults to asc.

Query parameter

limitintegerOptional

Positive maximum observation count.

Query parameter

Freshness & caching

Five-minute private cache. observedDate is the snapshot date; undisclosedPercent is a signed derived remainder, not observed retail ownership. Anomalies are flagged.

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/ownership-history?order=desc&apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "PLTR",
  "methodology": {
    "institutionalPercent": "Observed percentage held by institutions.",
    "insiderPercent": "Observed percentage held by insiders.",
    "undisclosedPercent": "100 - institutionsPercent - insidersPercent",
    "undisclosedPercentIsDerived": true,
    "negativeUndisclosedValuesPreserved": true
  },
  "data": [
    {
      "observedDate": "2026-09-18",
      "institutionsPercent": 64.75,
      "insidersPercent": 3.48,
      "undisclosedPercent": 31.77,
      "undisclosedPercentDerived": true,
      "interpretationStatus": "within_conventional_range",
      "interpretationFlags": []
    },
    {
      "observedDate": "2026-09-17",
      "institutionsPercent": 64.75,
      "insidersPercent": 3.48,
      "undisclosedPercent": 31.77,
      "undisclosedPercentDerived": true,
      "interpretationStatus": "within_conventional_range",
      "interpretationFlags": []
    },
    {
      "observedDate": "2026-09-16",
      "institutionsPercent": 64.74,
      "insidersPercent": 3.48,
      "undisclosedPercent": 31.78,
      "undisclosedPercentDerived": true,
      "interpretationStatus": "within_conventional_range",
      "interpretationFlags": []
    },
    {
      "observedDate": "2026-09-14",
      "institutionsPercent": 64.74,
      "insidersPercent": 3.48,
      "undisclosedPercent": 31.78,
      "undisclosedPercentDerived": true,
      "interpretationStatus": "within_conventional_range",
      "interpretationFlags": []
    },
    {
      "observedDate": "2026-09-11",
      "institutionsPercent": 64.77,
      "insidersPercent": 3.48,
      "undisclosedPercent": 31.75,
      "undisclosedPercentDerived": true,
      "interpretationStatus": "within_conventional_range",
      "interpretationFlags": []
    }
  ]
}

SUPPLEMENTAL DATASET

Direct company logo URLs

Every logo is hand-reviewed and normalized onto a visually balanced square canvas, producing polished, display-ready assets that stay crisp and consistent across dashboards, research tools, and light or dark interfaces.

ASSET CONVENTION · ACCOUNT REQUIREDhttps://••••••••••••••/••••••••••••••/{TICKER}.pngSign in to any API account, including Free Sandbox, to reveal direct asset URLs.

Display-ready. Assets are individually reviewed so they can be placed directly into a production interface.
Square and balanced. Consistent canvases and visual proportions prevent awkward sizing across company sets.
No quota use. Media requests do not consume API request capacity.
Separate contract. Logo URLs are not returned by the JSON endpoints.

ENDPOINT REFERENCE

Historical Analyst Consensus

Get historical analyst ratings, consensus scores and price targets for stock ranking and backtesting.

GET/v1/companies/{ticker}/analyst-rating-consensus-history

PARAMETERS4

1 required · 3 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

asOfDatedateOptional

Use YYYY-MM-DD to return one snapshot for that date, or the closest earlier date if unavailable. Ratings and targets are matched by snapshot date; missing fields remain null. Omit or leave blank for full history.

Query parameter

orderasc | descOptional

Observation order. Defaults to asc.

Query parameter

limitintegerOptional

Positive maximum observation count.

Query parameter

Freshness & caching

Five-minute private cache. Coverage counts snapshot dates before limit, up to asOfDate. Incomplete or empty ratings have no consensus score. No matching data returns [].

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/analyst-rating-consensus-history?apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "PLTR",
  "coverage": {
    "firstDate": "2020-11-13",
    "lastDate": "2026-10-05",
    "observationCount": 2153
  },
  "data": [
    {
      "asOfDate": "2022-08-04",
      "strongBuy": 0,
      "buy": 4,
      "hold": 6,
      "sell": 3,
      "strongSell": 0,
      "consensusRating": "hold",
      "consensusRatingValue": 3.08,
      "ratingsContributors": 13,
      "currency": "USD",
      "consensusPriceTarget": 13.3,
      "medianPriceTarget": 13,
      "lowPriceTarget": 6,
      "highPriceTarget": 21,
      "priceTargetContributors": 10
    },
    {
      "asOfDate": "2022-08-05",
      "strongBuy": 0,
      "buy": 4,
      "hold": 6,
      "sell": 3,
      "strongSell": 0,
      "consensusRating": "hold",
      "consensusRatingValue": 3.08,
      "ratingsContributors": 13,
      "currency": "USD",
      "consensusPriceTarget": 12.444444,
      "medianPriceTarget": 13,
      "lowPriceTarget": 6,
      "highPriceTarget": 20,
      "priceTargetContributors": 9
    },
    {
      "asOfDate": "2022-08-06",
      "strongBuy": 0,
      "buy": 4,
      "hold": 6,
      "sell": 3,
      "strongSell": 0,
      "consensusRating": "hold",
      "consensusRatingValue": 3.08,
      "ratingsContributors": 13,
      "currency": "USD",
      "consensusPriceTarget": 12.444444,
      "medianPriceTarget": 13,
      "lowPriceTarget": 6,
      "highPriceTarget": 20,
      "priceTargetContributors": 9
    }
  ]
}

ENDPOINT REFERENCE

Historical Company Guidance

Retrieve historical company guidance by announcement date and reporting period, including revenue forecasts and other financial or operating targets. Compare management outlooks with reported values, forecast ranges, guidance status and original source links.

GET/v1/companies/{ticker}/company-guidance-history

PARAMETERS6

1 required · 5 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

asOfDatedateOptional

Use YYYY-MM-DD to return each metric's latest guidance announced on or before that date, separately for each period type. Quarterly updates do not replace annual guidance. Each record keeps its actual announcementDate. Omit or leave blank for full history.

Query parameter

metricstringOptional

Return guidance for one metric, such as Revenue or Free cash flow. Matches the metric label without case sensitivity; omit for all metrics.

Query parameter

periodTypestringOptional

Choose annual, quarterly, halfyear, multiyear or other guidance. Omit to include every reporting-period type.

Query parameter

orderasc | descOptional

Observation order. Defaults to asc.

Query parameter

limitintegerOptional

Positive maximum observation count.

Query parameter

Freshness & caching

Five-minute private cache. Without asOfDate: full history; with it: latest guidance per metric and period type. Withdrawn values are null. No matching data returns [].

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/company-guidance-history?apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "PLTR",
  "coverage": {
    "firstDate": "2021-11-09",
    "lastDate": "2026-08-03",
    "observationCount": 89
  },
  "data": [
    {
      "announcementDate": "2021-11-09",
      "metric": "Operating margin",
      "scope": "Consolidated",
      "periodType": "quarterly",
      "periodEndDate": "2021-12-31",
      "basis": "Non-GAAP",
      "unit": "Percent",
      "value": 22,
      "low": null,
      "high": null,
      "valueText": "Adjusted operating margin of 22%.",
      "status": "issued",
      "sourceUrl": "https://www.sec.gov/Archives/edgar/…/d51038dex991.htm"
    },
    {
      "announcementDate": "2022-08-08",
      "metric": "Operating income",
      "scope": "Consolidated",
      "periodType": "quarterly",
      "periodEndDate": "2022-09-30",
      "basis": "Non-GAAP",
      "unit": "USD",
      "value": null,
      "low": 54000000,
      "high": 55000000,
      "valueText": "Adjusted income from operations of $54 - $55 million.",
      "status": "issued",
      "sourceUrl": "https://investors.palantir.com/files/…Q2-2022.pdf"
    },
    {
      "announcementDate": "2022-08-08",
      "metric": "Revenue",
      "scope": "Consolidated",
      "periodType": "quarterly",
      "periodEndDate": "2022-09-30",
      "basis": "Not specified",
      "unit": "USD",
      "value": null,
      "low": 474000000,
      "high": 475000000,
      "valueText": "Revenue of between $474 - $475 million.",
      "status": "issued",
      "sourceUrl": "https://www.sec.gov/Archives/edgar/…/d347534dex991.htm"
    }
  ]
}

ENDPOINT REFERENCE

List modeled Congress members

Discover stable member IDs and the current modeled-portfolio coverage available to your API plan.

GET/v1/congress/members

PARAMETERS0

0 required · 0 optional

Freshness & caching

Five-minute private cache. All plans see the member directory; portfolio and performance data remain plan-gated.

REQUEST

https://api.vizualstocks.com/v1/congress/members?apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "scope": {
    "coverageScope": "full_modeled_universe",
    "memberUniverseCount": 198
  },
  "generatedAtUtc": "2026-09-19T14:00:00.0000000Z",
  "members": [
    {
      "member": {
        "memberId": "bioguide-p000197",
        "name": "Nancy Pelosi",
        "chamber": "House",
        "party": "Democrat",
        "state": "CA",
        "district": 11,
        "bioguideId": "P000197",
        "photoUrl": "https://unitedstates.github.io/images/congress/225x275/P000197.jpg"
      },
      "portfolioAvailable": true,
      "freeSandboxAvailable": true,
      "modeledCoverageStartDate": "2021-09-20",
      "modeledCoverageEndDate": "2026-09-19",
      "lastUpdatedAtUtc": "2026-09-19T14:00:00.0000000Z",
      "coverage": {
        "pricedTradeCount": 42,
        "totalTradeCount": 45,
        "coveragePercent": 93.3,
        "hasCompleteWindow": true
      }
    }
  ]
}

ENDPOINT REFERENCE

Retrieve a modeled member portfolio

Retrieve VizualStocks-calculated current holdings and portfolio-level estimates without raw disclosures or transaction rows.

GET/v1/congress/members/{memberId}/portfolio

PARAMETERS1

1 required · 0 optional

memberIdstringRequired

Stable member ID returned by the member directory.

Path parameter

Freshness & caching

Five-minute private cache. Modeled values are estimates from disclosures and prices, not official holdings or raw trade records.

REQUEST

https://api.vizualstocks.com/v1/congress/members/bioguide-p000197/portfolio?apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "member": {
    "memberId": "bioguide-p000197",
    "name": "Nancy Pelosi",
    "chamber": "House",
    "party": "Democrat",
    "state": "CA",
    "district": 11,
    "bioguideId": "P000197",
    "photoUrl": "https://unitedstates.github.io/images/congress/225x275/P000197.jpg"
  },
  "generatedAtUtc": "2026-09-19T14:00:00.0000000Z",
  "estimatedOpenValue": 2485000,
  "modeledCostBasis": 1930000,
  "realizedGain": 85000,
  "unrealizedGain": 555000,
  "totalGain": 640000,
  "coverage": {
    "pricedTradeCount": 42,
    "totalTradeCount": 45,
    "coveragePercent": 93.3,
    "hasCompleteWindow": true
  },
  "holdings": [
    {
      "ticker": "NVDA",
      "assetDescription": "NVIDIA Corporation",
      "estimatedShares": 7500,
      "estimatedValue": 1312500,
      "portfolioWeightPercent": 52.82,
      "costBasis": 900000,
      "currentPrice": 175,
      "unrealizedGain": 412500,
      "performancePercent": 45.83
    }
  ]
}

ENDPOINT REFERENCE

Retrieve member performance

Compare a modeled member portfolio with its benchmark over one supported measurement window.

GET/v1/congress/members/{memberId}/performance

PARAMETERS2

1 required · 1 optional

memberIdstringRequired

Stable member ID returned by the member directory.

Path parameter

windowYTD | 1Y | 2Y | 3Y | MAXOptional

Performance window. Case-insensitive; defaults to 1Y and returns the canonical uppercase value.

Query parameter

Freshness & caching

Five-minute private cache. window selects dates, returns and chart; default is 1Y.

REQUEST

https://api.vizualstocks.com/v1/congress/members/bioguide-p000197/performance?window=1Y&apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "member": {
    "memberId": "bioguide-p000197",
    "name": "Nancy Pelosi",
    "chamber": "House",
    "party": "Democrat",
    "state": "CA",
    "district": 11,
    "bioguideId": "P000197",
    "photoUrl": "https://unitedstates.github.io/images/congress/225x275/P000197.jpg"
  },
  "selectedWindow": "1Y",
  "periodStartDate": "2025-09-19",
  "periodEndDate": "2026-09-19",
  "generatedAtUtc": "2026-09-19T14:00:00.0000000Z",
  "portfolioReturnPercent": 24.6,
  "benchmarkReturnPercent": 17.2,
  "excessReturnPercent": 7.4,
  "cagrPercent": 24.6,
  "benchmarkCagrPercent": 17.2,
  "coverage": {
    "pricedTradeCount": 18,
    "totalTradeCount": 19,
    "coveragePercent": 94.7,
    "hasCompleteWindow": true
  },
  "chart": [
    {
      "date": "2026-09-19",
      "portfolioReturnPercent": 24.6,
      "benchmarkReturnPercent": 17.2
    }
  ]
}

ENDPOINT REFERENCE

Rank modeled member portfolios

Rank eligible modeled portfolios for the selected period, with optional chamber, party, and state filters.

GET/v1/congress/leaderboard

PARAMETERS4

0 required · 4 optional

windowYTD | 1Y | 2Y | 3Y | MAXOptional

Ranking window. Case-insensitive; defaults to 1Y.

Query parameter

chamberstringOptional

Case-insensitive chamber filter.

Query parameter

partystringOptional

Case-insensitive party filter.

Query parameter

statestringOptional

Case-insensitive state filter.

Query parameter

Freshness & caching

Ranks are recalculated for the chosen window and eligible members; Free Sandbox covers five members, not all Congress.

REQUEST

https://api.vizualstocks.com/v1/congress/leaderboard?window=1Y&apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "scope": {
    "coverageScope": "sandbox_curated_members",
    "memberUniverseCount": 5
  },
  "selectedWindow": "1Y",
  "periodStartDate": "2025-09-19",
  "periodEndDate": "2026-09-19",
  "generatedAtUtc": "2026-09-19T14:00:00.0000000Z",
  "members": [
    {
      "rank": 1,
      "member": {
        "memberId": "bioguide-p000197",
        "name": "Nancy Pelosi",
        "chamber": "House",
        "party": "Democrat",
        "state": "CA",
        "district": 11,
        "bioguideId": "P000197",
        "photoUrl": "https://unitedstates.github.io/images/congress/225x275/P000197.jpg"
      },
      "portfolioReturnPercent": 24.6,
      "benchmarkReturnPercent": 17.2,
      "excessReturnPercent": 7.4,
      "estimatedOpenValue": 2485000,
      "holdingCount": 8,
      "coverage": {
        "pricedTradeCount": 18,
        "totalTradeCount": 19,
        "coveragePercent": 94.7,
        "hasCompleteWindow": true
      }
    }
  ]
}

ENDPOINT REFERENCE

Find modeled portfolio holders by ticker

Find current modeled member portfolios that hold a company without exposing the underlying disclosure or transaction rows.

GET/v1/congress/stocks/{ticker}/holders

PARAMETERS1

1 required · 0 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

Freshness & caching

Five-minute private cache. Free Sandbox searches five members across its 20 companies; paid plans search the full modeled universe.

REQUEST

https://api.vizualstocks.com/v1/congress/stocks/NVDA/holders?apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "NVDA",
  "scope": {
    "coverageScope": "sandbox_curated_members",
    "memberUniverseCount": 5
  },
  "generatedAtUtc": "2026-09-19T14:00:00.0000000Z",
  "holders": [
    {
      "member": {
        "memberId": "bioguide-p000197",
        "name": "Nancy Pelosi",
        "chamber": "House",
        "party": "Democrat",
        "state": "CA",
        "district": 11,
        "bioguideId": "P000197",
        "photoUrl": "https://unitedstates.github.io/images/congress/225x275/P000197.jpg"
      },
      "estimatedShares": 7500,
      "estimatedValue": 1312500,
      "portfolioWeightPercent": 52.82,
      "costBasis": 900000,
      "unrealizedGain": 412500,
      "performancePercent": 45.83,
      "coverage": {
        "pricedTradeCount": 42,
        "totalTradeCount": 45,
        "coveragePercent": 93.3,
        "hasCompleteWindow": true
      }
    }
  ]
}

ENDPOINT REFERENCE

Retrieve the latest Rapid Earnings Snapshot

Get newly reported GAAP results and available company KPIs from the first earnings document we can find—typically within 30 seconds of its release.

GET/v1/companies/{ticker}/earnings/latest

PARAMETERS2

1 required · 1 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

includeSourcesbooleanOptional

Defaults to false. When true, adds verified source references for returned KPI and segment values. Partial coverage returns only the available references.

Query parameter

Freshness & caching

30-second private cache lifetime. Sources appear only with includeSources=true; an empty sources array means no reviewed citation yet.

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/earnings/latest?apikey=YOUR_API_KEY

RESPONSE

200 OK

{
  "ticker": "PLTR",
  "normalizedPeriod": "Q2'26",
  "fiscalYear": 2026,
  "fiscalQuarter": 2,
  "periodEnd": "2026-06-30",
  "reportingCurrency": "USD",
  "revenue": 1935464000,
  "grossProfit": 1638594000,
  "netIncome": 1065962000,
  "epsBasic": 0.41,
  "epsGaap": 0.41,
  "salesGeneralAndAdmin": 310000000,
  "researchAndDevelopment": 430000000,
  "sellingAndMarketingExpenses": 220000000,
  "generalAndAdministrativeExpenses": 90000000,
  "operatingExpenses": 1100000000,
  "sharesOutstanding": 2599410000,
  "cashAndEquivalents": 5900000000,
  "marketableSecurities": 1800000000,
  "longTermDebt": null,
  "operatingCashFlow": 880000000,
  "freeCashFlow": 790000000,
  "customerCount": 1049,
  "commercialCustomerCount": 873,
  "remainingPerformanceObligations": 4900000000,
  "ruleOf40": 149,
  "netDollarRetention": 153
}

OPERATIONAL REFERENCE

Predictable behavior in production

Shared conventions apply across V1 so integrations can reuse optional pagination, caching, error handling, and versioning logic.

Pagination

Only the company catalog supports opt-in pagination. Both page and pageSize must be supplied explicitly; otherwise the complete filtered catalog is returned. No default page size or maximum page size is imposed.

History ordering

Chart and history endpoints default to order=asc. Use order=desc&limit=1 for the latest observation. On estimate revisions, the limit applies independently to each target period.

Caching

Successful responses use private Cache-Control lifetimes appropriate to each dataset. Documented authentication, validation, access and quota errors use no-store.

Rapid earnings

Returns newly reported GAAP results and available company KPIs from the first earnings document we can find, typically within 30 seconds of publication.

Versioning

Breaking changes require a new major path such as /v2. Additive response fields, such as isMonetary, may be introduced within V1. Clients should tolerate unknown fields.

Rate limits

Limits are shared across the account's API keys. HTTP 429 distinguishes per-minute throttling (rate_limit_exceeded), request allowance exhaustion (request_quota_exceeded), and transfer allowance exhaustion (transfer_quota_exceeded). Plan changes apply the new plan's allowances when the change takes effect.

Error catalog

HTTP	Code	Meaning
`400`	invalid_parameter	A path or query parameter is invalid.
`401`	missing_api_key	The API key is missing from the query parameter and request header.
`401`	invalid_api_key	The supplied key is invalid or revoked.
`403`	api_access_inactive	API access for the account is inactive.
`403`	api_plan_not_configured	The account's API plan is not fully configured.
`403`	company_not_available_on_plan	The company is outside the current plan's catalog.
`403`	metric_not_available_on_plan	The metric is outside the current plan's catalog.
`404`	company_not_found	No supported company matches the ticker.
`404`	metric_not_found	The company does not expose the requested metric ID.
`404`	earnings_snapshot_not_found	No Rapid Earnings Snapshot is available.
`429`	rate_limit_exceeded	The account-level requests-per-minute limit was exceeded.
`429`	request_quota_exceeded	The request allowance for the current usage period is exhausted.
`429`	transfer_quota_exceeded	The transfer allowance for the current usage period is exhausted.

Unexpected server or gateway failures can return HTTP 5xx without this JSON envelope. Check the status and content type before parsing an error body.

Usage and retry headers

Responses that reach quota enforcement include account-level usage headers. A per-minute rejection returns rate-limit headers and Retry-After; authentication failures may not include usage headers. Reset values are Unix timestamps in seconds.

Headers	Meaning
`X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset`	Rolling-minute request capacity, remaining capacity and reset time.
`X-Request-Limit / X-Request-Remaining / X-Request-Reset`	Request allowance for the current daily or monthly usage period.
`X-Transfer-Limit-Bytes / X-Transfer-Remaining-Bytes / X-Transfer-Reset`	Transfer allowance and remaining capacity in bytes, plus the period reset time.
`Retry-After`	Seconds to wait after a per-minute rate_limit_exceeded response.

V1 CONTRACT

Monetary metadata

The metric catalog, all-company metrics and single-metric history responses now include isMonetary. Values and source metadata retain their existing shapes.

September 18, 2026

Rotate to portrait

Public API v1 reference

Make your first request

Add your API key

Choose an endpoint

Handle the response

Direct success response

Error envelope

A stable contract for company data

Flexible ticker input

Stable metric IDs

KPIs versus segments

History stays durable

Issuer identity plus chart labels

Base-unit numbers

Currency versus counts

The scale is explicit

Keep the value, choose the display

Optional, incremental evidence

Discover everything, then expand access

Calculated portfolios, not trade feeds

List companies

Retrieve the company metric catalog

Retrieve metric history

Retrieve all company metrics

Retrieve short interest

Retrieve analyst estimate revision trends

Retrieve historical ownership

Direct company logo URLs

Historical Analyst Consensus

Historical Company Guidance

List modeled Congress members

Retrieve a modeled member portfolio

Retrieve member performance

Rank modeled member portfolios

Find modeled portfolio holders by ticker

Retrieve the latest Rapid Earnings Snapshot

Predictable behavior in production

Pagination

History ordering

Caching

Rapid earnings

Versioning

Rate limits

Error catalog

Usage and retry headers