# Earnings by Ticker

`GET` `/v1/earnings/{ticker}`

Retrieve reported and estimated earnings for a ticker: report date, actual vs estimated EPS and revenue for each period. Use this to see whether a company beat or missed expectations, track the earnings calendar historically or feed surprise metrics into research tools. Results are ordered by report date, most recent first.

## Use cases

- Earnings surprise and beat/miss analysis
- Historical EPS and revenue trend charts
- Pre-earnings research and estimate comparison
- Event-driven trading or alerting around report dates

## Input parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ticker` | string | Yes | Ticker. |
| `limit` | integer | No | Max results (default 500). |

## Output parameters

| Name | Type | Description |
| --- | --- | --- |
| `results` | array | Earnings reports, most recent first. |
| `results[].ticker` | string | Ticker. |
| `results[].report_date` | string | Report date (YYYY-MM-DD). |
| `results[].eps_actual` | float | Reported EPS. |
| `results[].eps_estimated` | float | Consensus EPS estimate. |
| `results[].revenue_actual` | float | Reported revenue. |
| `results[].revenue_estimated` | float | Consensus revenue estimate. |
| `results[].last_updated` | string | Last update timestamp (ISO 8601). |
| `count` | integer | Number of earnings records returned. |

## Example response

```json
{
  "results": [
    {
      "ticker": "AAPL",
      "report_date": "2026-07-30",
      "eps_actual": null,
      "eps_estimated": 1.86,
      "revenue_actual": null,
      "revenue_estimated": 108393400000,
      "last_updated": "2026-06-06"
    },
    {
      "ticker": "AAPL",
      "report_date": "2026-04-30",
      "eps_actual": 2.01,
      "eps_estimated": 1.95,
      "revenue_actual": 111184000000,
      "revenue_estimated": 109457600000,
      "last_updated": "2026-06-06"
    }
  ],
  "count": 27
}
```

## Examples

### cURL

```bash
curl "https://api.vantafin.com/v1/earnings/AAPL?apiKey=$VANTAFIN_API_KEY"
```

### Python

```python
from vantafin import RESTClient

client = RESTClient("vf-live-your_api_key")

result = client.get_earnings("AAPL")

print(result)
```

### JavaScript

```javascript
import { RestClient } from "vantafin";

const client = new RestClient("vf-live-your_api_key");

const result = await client.getEarnings("AAPL");

console.log(result);
```

### Go

```go
package main

import (
	"fmt"
	"log"

	"github.com/vantafin/vantafin-go"
)

func main() {
	client := vantafin.NewClient("vf-live-your_api_key")

	result, err := client.GetEarnings("AAPL")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result)
}
```

### Java

```java
import com.vantafin.RestClient;

public class Example {
    public static void main(String[] args) throws Exception {
        RestClient client = new RestClient("vf-live-your_api_key");

        Object result = client.getEarnings("AAPL");

        System.out.println(result);
    }
}
```

### Ruby

```ruby
require "vantafin"

client = Vantafin::RestClient.new("vf-live-your_api_key")

result = client.get_earnings("AAPL")

pp result
```