Getting started

Versioning

The API answers in one of three response formats. These pages document v4, which is what api.earningscall.dev returns unless you ask for another.

Choosing a version#

You do not have to choose: a request to api.earningscall.dev gets v4. To name a version yourself, the API looks in three places, in this order:

The path. /v4/transcript is v4, whatever else the request says.
The x-api-version-schema header. Used when the path names no version.
The hostname. Each host has a default, used when neither of the above is present.

# No version: the host's default -- what the examples in these docs do
curl 'https://edge.alpha.earningscall.dev/events?apikey=demo&exchange=NASDAQ&symbol=AAPL'

# In the path
curl 'https://edge.alpha.earningscall.dev/v4/events?apikey=demo&exchange=NASDAQ&symbol=AAPL'

# Or as a header
curl -H 'x-api-version-schema: v4' \
  'https://edge.alpha.earningscall.dev/events?apikey=demo&exchange=NASDAQ&symbol=AAPL'

# No version: the host's default -- what the examples in these docs do
curl 'https://edge.alpha.earningscall.dev/events?apikey=demo&exchange=NASDAQ&symbol=AAPL'

# In the path
curl 'https://edge.alpha.earningscall.dev/v4/events?apikey=demo&exchange=NASDAQ&symbol=AAPL'

# Or as a header
curl -H 'x-api-version-schema: v4' \
  'https://edge.alpha.earningscall.dev/events?apikey=demo&exchange=NASDAQ&symbol=AAPL'

Every response says which version answered, in the x-api-version-schema response header. A path that names a version we do not have, such as /v9/events, is a 404, in plain text rather than JSON.

A header value the API does not recognise, such as v5 or 4, is not rejected: the request is answered in v2, whose errors have no body. If a response is not the shape you expected, that response header is the first thing to read.

Tip

A version in the path cannot be changed by anything else: a proxy can drop a header, and a host's default is ours to choose. A path that says /v4/ is answered in v4.

The versions#

Version	Status	Default on
v4	Current. These pages document it.	`api.earningscall.dev`
v3	Frozen.	Other hosts
v2	Frozen. What the Python and JavaScript SDKs use.	`v2.api.earningscall.biz`

Frozen means the shape of a response will not change: no field is renamed, moved or removed. A new field may still be added, so write clients that ignore fields they do not recognise.

Response envelope#

In v4, every endpoint that returns a list returns an object: the list under a name of its own, and a meta object beside it.

{
  "symbols": [
    {
      "exchange": "NASDAQ",
      "name": "Microsoft Corporation",
      "symbol": "MSFT"
    }
  ],
  "meta": {
    "request_id": "3ee06a96-bc76-4745-a7d9-eec0fe8ca60c",
    "total": 1,
    "next_cursor": null
  }
}

request_id — identifies the request that produced this body. The x-request-id response header carries the same value.
total — how many items the list holds.
next_cursor — always null today. It is there so paging can be added later without changing the shape.

Search returns one page of a longer list, so its meta has more in it:

{
  "request_id": "4d252c78-0368-4eae-9f32-56401ad3e81f",
  "total": 10000,
  "from": 0,
  "size": 5,
  "next_cursor": null
}

total — the number of matching calls, counted up to 10000. A query that matches more than that reports 10000.
from, size — the page this response holds: where it starts and how many results it may contain. size is the value that was used, which can be lower than the one you sent: the demo key is capped at 10 and reports 10 however many you ask for.

What v4 changes#

If you are moving from v2.api.earningscall.biz, these are the responses that differ. Audio and slides are the same on every version.

Endpoint	v2 and v3	v4
/symbols	A bare array	`{ symbols, meta }`
/calendar	A bare array	`{ events, meta }`
/events	`{ company_name, events }`	`{ exchange, symbol, company_name, events, meta }`
/live	`{ events, count }`; fields such as `companyName`	`{ events, meta }`; fields such as `company_name`
/search	`{ results, total, from, size, took }`	`{ results, took, meta }`
/transcript	`speaker` is an id; names are in `speaker_name_map_v2`	`speaker` is `{ id, name, title }`
Errors	v2: an empty body. v3: JSON	JSON, with a `request_id`

A v4 transcript also says which call it is: it carries the exchange and symbol, in upper case however you wrote them, and the level. Its event has no is_published, which v2 and v3 send as null.

SDKs#

The Python and JavaScript SDKs call v2 and hand back their own objects, so nothing on this page changes how you use them. The response examples on the endpoint pages show what the REST API returns to curl.