API DOCUMENTATION

Public API v1 reference

Endpoints, parameters, and response structures for companies, segments, KPIs, short interest, and earnings data.

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 and handle errors using 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"
  }
]

Error envelope

4xx / 5xx

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

Public documentation, protected data

This page shows contracts and illustrative response shapes only. 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

Uppercase tickers

Tickers are case-insensitive in requests and normalized to uppercase in company and earnings responses.

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.

PLAN ACCESS

One integration at every tier

Free Sandbox uses these same V1 routes for 16 live-demo companies, five curated metrics per company, and full available history. Upgrading the account unlocks the broader catalog without changing URLs, API keys, or response contracts.

ENDPOINT REFERENCE

List companies

Discover the companies and public company-metric coverage available to the authenticated API plan through V1.

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

The company catalog uses a short private cache lifetime. Omitting page and pageSize returns the complete filtered catalog; pagination is never inferred.

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,
    "coverage": {
      "companyKpiCount": 17,
      "segmentMetricCount": 2,
      "activeMetricCount": 19,
      "discontinuedMetricCount": 0
    }
  },
  {
    "ticker": "TSLA",
    "name": "Tesla Inc",
    "marketCap": 1100000000000,
    "hasCompanyKpis": true,
    "hasSegments": true,
    "hasShortInterest": true,
    "hasRapidEarnings": 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,
    "coverage": {
      "companyKpiCount": 1,
      "segmentMetricCount": 17,
      "activeMetricCount": 8,
      "discontinuedMetricCount": 10
    }
  },
  {
    "ticker": "MSFT",
    "name": "Microsoft Corp",
    "marketCap": 3700000000000,
    "hasCompanyKpis": true,
    "hasSegments": true,
    "hasShortInterest": true,
    "hasRapidEarnings": 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

Metric catalogs use a short private cache lifetime. Discontinued metrics remain discoverable when status is all or discontinued.

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"
      ],
      "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"
      ],
      "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"
      ],
      "valueFormat": "percentage",
      "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"
      ],
      "valueFormat": "percentage",
      "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}

PARAMETERS5

2 required · 3 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

Freshness & caching

History uses a 30-second private cache lifetime. Request the latest usable point with order=desc&limit=1.

REQUEST

https://api.vizualstocks.com/v1/companies/PLTR/metrics/customerCount?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",
      "value": 1049
    },
    {
      "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

PARAMETERS6

1 required · 5 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

Freshness & caching

All Company Metrics uses a 30-second private cache lifetime and deterministic period, metric, and segment-group ordering.

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,
      "governmentRevenue": 990000000
    },
    {
      "normalizedPeriod": "Q1'26",
      "fiscalYear": 2026,
      "fiscalQuarter": 1,
      "periodEnd": "2026-03-31",
      "commercialRevenue": 774000000,
      "governmentRevenue": 858000000
    }
  ],
  "metrics": [
    {
      "metricId": "commercialRevenue",
      "name": "Commercial Revenue",
      "description": "Revenue from commercial customers during the quarter.",
      "type": "segment",
      "status": "active",
      "valueFormat": "number",
      "discontinuation": null
    },
    {
      "metricId": "governmentRevenue",
      "name": "Government Revenue",
      "description": "Revenue from government customers during the quarter.",
      "type": "segment",
      "status": "active",
      "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.

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

Revision histories use a five-minute private cache. normalizedPeriod filters one exact chart period; no period or history limit is otherwise applied unless limit is supplied explicitly.

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": "Q3'26",
          "history": [
            {
              "collectedDate": "2026-07-28",
              "revenueEstimate": 2001558610,
              "epsEstimate": 0.36985
            },
            {
              "collectedDate": "2026-07-31",
              "revenueEstimate": 2001557876,
              "epsEstimate": 0.36978
            },
            {
              "collectedDate": "2026-08-08",
              "revenueEstimate": 2161932973,
              "epsEstimate": 0.41307
            }
          ]
        }
      ]
    }
  ]
}

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 seven JSON endpoints.

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

PARAMETERS1

1 required · 0 optional

tickerstringRequired

Case-insensitive company ticker.

Path parameter

Freshness & caching

The latest snapshot uses a 30-second private cache lifetime so newly persisted earnings values become visible quickly.

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. Error responses 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. Adding a nullable field is not considered breaking.

Rate limits

A limit breach uses HTTP 429 with rate_limit_exceeded. Conventional limit headers will accompany enforced plan quotas.

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`	forbidden	The key cannot access the requested capability.
`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 applicable request limit was exceeded.
`500`	internal_error	An unexpected server error occurred.

V1 CONTRACT

Public contract

Seven authenticated JSON endpoints with direct response shapes, stable metric identifiers, issuer period metadata, and normalized base-unit values.

August 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

Uppercase tickers

Stable metric IDs

KPIs versus segments

History stays durable

Issuer identity plus chart labels

Base-unit numbers

One integration at every tier

List companies

Retrieve the company metric catalog

Retrieve metric history

Retrieve all company metrics

Retrieve short interest

Retrieve analyst estimate revision trends

Direct company logo URLs

Retrieve the latest Rapid Earnings Snapshot

Predictable behavior in production

Pagination

History ordering

Caching

Rapid earnings

Versioning

Rate limits

Error catalog