How to Get Company Earnings Data via API

Quick Answer

To get company earnings data via API, call Valyu’s Search API with the company and reporting period and target valyu/valyu-earnings-US. The documented dataset returns structured actual EPS, analyst EPS estimates, earnings surprises, report dates, fiscal period ends, and currency, with company metadata. Use these records to check a beat or miss, compare quarters, or build an earnings table.

{
  "query": "Microsoft fiscal Q4 2024 earnings actual EPS analyst estimate surprise",
  "included_sources": [
    "valyu/valyu-earnings-US"
  ]
}

This guide focuses on the fields documented for valyu/valyu-earnings-US. The request examples target that source; the field descriptions below come from its response schema rather than a demonstrated live response in this article.

If you're an agent: Set up Valyu and make your first search.

If you're a human: Create an account and get an API key.

MCP onboarding: Connect your agent to https://mcp.valyu.ai/mcp and follow the MCP setup guide for authentication.

What does the earnings-US dataset return?

valyu/valyu-earnings-US provides structured earnings records for US public companies. Its documented content field is an array of earnings data points, rather than an application-generated summary.

Accompanying metadata identifies the company with company_name and symbol, plus a retrieval timestamp. Keep those fields with the earnings records so a downstream table or comparison retains company identity and context.

The tables and examples here are scoped to these documented fields. See the financial data guide and data coverage reference for dataset availability. Access to specialised financial datasets depends on your account.

How should you write an earnings-data query?

Include the company, fiscal period, and fields you want. A precise period is useful when you need historical records rather than whichever report happens to be most recent. The company’s fiscal calendar may differ from the calendar year.

These are query patterns to adapt, not additional observed results. Target valyu/valyu-earnings-US in included_sources and inspect the returned company metadata and fiscal dates before selecting a record.

Retrieve earnings data with Code

Choose either SDK. Install valyu for Python with pip install valyu, or valyu-js for TypeScript with pnpm add valyu-js.

Set VALYU_API_KEY in your environment and keep the key on the server.

from valyu import Valyu
 
client = Valyu()
response = client.search(
    "Microsoft fiscal Q4 2024 earnings actual EPS analyst estimate surprise",
    included_sources=["valyu/valyu-earnings-US"],
)
if not response.success:
    raise RuntimeError("Earnings data search failed")
 
for result in response.results:
    if result.source == "valyu/valyu-earnings-US":
        print(result.metadata)
        print(result.content)

The examples check response.success, select results from valyu/valyu-earnings-US, and print the company metadata and returned records.

SDK references: Python search and TypeScript search.

How do you identify an earnings beat or miss?

Compare eps_actual with eps_estimate from the same earnings record. A reported EPS above the estimate is a beat; below the estimate is a miss; equality means the estimate was met. Keep the supplied surprise and surprise_percentage alongside the comparison.

Do not classify a record when the actual or estimate is missing. Check that the values use the same accounting basis, and avoid rounding before comparing them. If you calculate a percentage yourself, document the denominator and explicitly handle zero or negative estimates rather than assuming one formula works for every record.

What should you check before comparing earnings records?

• Company identity: confirm the returned symbol and company_name.
• Fiscal period: use fiscal_date_ending to identify the period being reported.
• Report date: date identifies the earnings report and is separate from the fiscal period end.
• Currency and accounting basis: compare equivalent figures and do not infer an accounting basis from the field name alone.
• Missing values: retain unavailable estimates or actuals as missing rather than treating them as zero.
• Record selection: inspect all returned records instead of assuming the first one matches the requested quarter.

What can you build with earnings-US data?

• A quarterly earnings table with actual EPS, estimated EPS, and surprise.
• A beat-or-miss view across a watchlist, retaining the report and fiscal dates.
• A company earnings history for comparing reported EPS across periods.
• A research tool that returns the earnings record behind an answer instead of relying on a model’s memory.

For a comparison across companies, select a corresponding reporting period for each company and preserve the currency. For a comparison over time, retain each record’s fiscal period end and avoid mixing quarterly and annual observations.

FAQ

What earnings data does valyu/valyu-earnings-US provide?

Its documented schema includes actual EPS, estimated EPS, earnings surprise, surprise percentage, earnings report date, fiscal period end, and currency. Metadata identifies the company, ticker symbol, and retrieval timestamp.

Can I search for earnings data without a ticker?

The source-specific request pattern uses a company name and fiscal period. Confirm the resolved company name and ticker in the returned metadata before using the records.

Can I retrieve historical earnings records?

Include the desired fiscal year or quarter in the query. Then inspect fiscal_date_ending and the report date in the returned records. Coverage and available observations depend on the source and your account’s access.

What is the difference between the earnings date and fiscal period end?

The date field identifies the earnings report date. The fiscal_date_ending field identifies the end of the period being reported. Use the fiscal date to match a quarter and the report date to place the announcement on a timeline.

How do I check whether a company beat earnings estimates?

Compare eps_actual with eps_estimate in the same record, and retain the provided surprise fields. If either value is missing, do not classify the record as a beat or miss.

Does every earnings record contain an analyst estimate?

Do not assume every field is populated for every observation. Check the returned record and preserve missing estimates as missing. An absent estimate is not the same as an estimate of zero.

Can an agent retrieve this dataset through MCP?

Connect the agent to Valyu’s hosted MCP endpoint and follow the setup guide for authentication. Request the company, fiscal period, and earnings fields, with earnings-US as the source. Dataset access follows the connected account.

Can I compare earnings across companies or quarters?

Yes, using the returned earnings records in application code. Match the reporting periods, company identities, currencies, and accounting bases before comparing values. Keep each record’s dates and source context with the result.

Create a Valyu account, enable the dataset access you need, and request the company and fiscal period you want to inspect.