# Option Expirations

Get a list of current or historical option expiration dates for an underlying symbol. If no optional parameters are used, the endpoint returns all expiration dates in the option chain.

## Endpoint
```
https://api.marketdata.app/v1/options/expirations/{underlyingSymbol}/
```
### Method
```
GET
```
## Request Example

### HTTP

**GET** [https://api.marketdata.app/v1/options/expirations/AAPL/](https://api.marketdata.app/v1/options/expirations/AAPL/)

### JavaScript

```js title="app.js"
import { MarketDataClient } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  const data = await client.options.expirations("AAPL");
  console.log(`Updated: ${data.updated}`);
  for (const exp of data.expirations) {
    console.log(exp);
  }
} catch (error) {
  console.error(error);
}
```

### TypeScript

```typescript title="app.ts"
import { MarketDataClient } from "@marketdata/sdk";
import type { OptionsExpirationsResponse } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  const data: OptionsExpirationsResponse = await client.options.expirations("AAPL");
  console.log(`Updated: ${data.updated}`);
  for (const exp of data.expirations) {
    console.log(exp);
  }
} catch (error) {
  console.error(error);
}
```

### Python

```python title="app.py"
from marketdata import MarketDataClient

client = MarketDataClient()
expirations = client.options.expirations("AAPL")
print(expirations)
```

### Go

```go title="optionExpirations.go"

import (
  "fmt"

  api "github.com/MarketDataApp/sdk-go"
)

func ExampleOptionsExpirationsRequest() {
	expirations, err := OptionsExpirations().UnderlyingSymbol("AAPL").Get()
	if err != nil {
		fmt.Print(err)
		return
	}

	for _, expiration := range expirations {
		fmt.Println(expiration)
	}
}
```

### PHP

```php title="optionExpirations.php"
use MarketDataApp\Client;

$client = new Client();
$expirations = $client->options->expirations("AAPL");

// Display all expiration dates
echo $expirations;
```

### Java

```java title="OptionExpirations.java"
import com.marketdata.sdk.MarketDataClient;
import com.marketdata.sdk.options.OptionsExpirationsRequest;

try (MarketDataClient client = new MarketDataClient()) {
    client.options().expirations(OptionsExpirationsRequest.of("AAPL")).values().forEach(System.out::println);
}
```

### Kotlin

```kotlin title="OptionExpirations.kt"
import com.marketdata.sdk.MarketDataClient
import com.marketdata.sdk.options.OptionsExpirationsRequest

MarketDataClient().use { client ->
    client.options().expirations(OptionsExpirationsRequest.of("AAPL")).values().forEach(::println)
}
```

### C#

```csharp title="OptionExpirations.cs"
using MarketDataApp;

using var client = await MarketDataClient.CreateAsync();

foreach (var expiration in (await client.Options.GetExpirationsAsync("AAPL")).Values)
{
    Console.WriteLine(expiration);
}
```

## Response Example

```json
{
  "s": "ok",
  "expirations": [
    "2022-09-23",
    "2022-09-30",
    "2022-10-07",
    "2022-10-14",
    "2022-10-21",
    "2022-10-28",
    "2022-11-18",
    "2022-12-16",
    "2023-01-20",
    "2023-02-17",
    "2023-03-17",
    "2023-04-21",
    "2023-06-16",
    "2023-07-21",
    "2023-09-15",
    "2024-01-19",
    "2024-06-21",
    "2025-01-17"
  ],
  "updated": 1663704000
}
```

## Request Parameters

### Required

- **underlyingSymbol** `string`

  The underlying ticker symbol for the options chain you wish to lookup.

### Optional

- **strike** `number`

  Limit the lookup of expiration dates to the strike provided. This will cause the endpoint to only return expiration dates that include this strike.

- **date** `date`

  Use to lookup a historical list of expiration dates from a specific previous trading day. If date is omitted the expiration dates will be from the current trading day during market hours or from the last trading day when the market is closed. Accepted date inputs: `ISO 8601`, `unix`, `spreadsheet`.

## Response Attributes

### Success

- **s** `string`

  Status will always be `ok` when there is strike
  data for the underlying/expirations requested.

- **expirations** `array[date]`

  The expiration dates requested for the underlying with the option strikes for each expiration.

- **updated** `date`

  The date and time of this list of options expirations was last updated. All timestamps use US Eastern Time (America/New_York). For historical expirations, this should match the `date` parameter. See [Response Timezone](https://www.marketdata.app/docs/docs/api/dates-and-times#response-timezone) for details.

### No Data

- **s** `string`

  Status will be `no_data` if no data is found for the request.

- **nextTime** `number` optional

  Unix time of the next quote if there is no data in the requested period, but there is data in a subsequent period.

- **prevTime** `number` optional

  Unix time of the previous quote if there is no data in the requested period, but there is data in a previous period.

### Error

- **s** `string`

  Status will be `error` if the request produces an error response.

- **errmsg** `string`
  An error message.

## Usage Information

### Data Availability

This endpoint provides options expiration dates data. This endpoint does not require any exchange entitlements and is available to all users.

| User Type | Exchange Entitlement | Data Type    |
|-----------|----------------------|--------------|
| All Users | Not Required         | Options Data |

### Pricing

The cost of using the expirations API endpoint is 1 credit per API call.

| Data Type        | Cost Basis   | Credits Required per Unit |
|------------------|--------------|---------------------------|
| Expirations Data | Per API call | 1 credit                  |