Signals API Reference

Free Trial ➡

This REST API returns structured data for various signals such as unusual options activity.

Best Practices

For optimal performance, we have a few recommendations.

Limit query, improve performance

Limiting the scope of the query will directly improve the latency of the API. This can be accomplished by using parameters such as parameters[tickers] and parameters[date], or (preferably) by using parameters[updated] for deltas.

Using Deltas

A common pattern is to use a delta to query for the latest change in a dataset. By reducing the amount of data available in the query, it will produce results with the least amount of latency and limited data an application will have to traverse.

In our case, we recommend tracking and querying by the latest updated timestamp.

One caveat to allow for some latency and second-only timestamps: when querying, set parameters[updated] to a value 5 seconds earlier than you actually want. A query may look like:

/signal/option_activity?parameters[updated]=LAGGED_TIMESTAMP Where LAGGED_TIMESTAMP is set to be five seconds less than the maximum value of the updated field in rows already pulled from our API.

API Endpoint
https://api.benzinga.com/api/v1
Response Content-Types

application/json, application/xml (deprecated)

Schemes

https, http

Version

1.0.0

Authentication

token authentication

Type:
apiKey
Name:
token
In:
query

Playground

Endpoints

GET /signal/option_activity

Returns option activity signals

Parameters

NameTypeLocationDescription
acceptstring , x ∈ { application/json (default) , application/xml (deprecated) }header

Specifies return format. Query parameters work the same for both formats.

pageintegerquery

Page offset.

pagesizeintegerquery

Number of results returned. Limit 1000

parameters[date]string (YYYY-MM-DD)query

Date to query for data. Shorthand for date_from and date_to if they are the same. Defaults for latest.

parameters[date_from]string (YYYY-MM-DD)query

Date to query from point in time.

parameters[date_to]string (YYYY-MM-DD)query

Date to query to point in time.

parameters[tickers]string (csv)query

One or more ticker symbols separated by a comma.

parameters[updated]integer (int64)query

Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.

Responses

CodeModelDescription
200 OKoption-activity

success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-MM-DD)",
    "time": "string (HH:MM:SS)",
    "ticker": "string",
    "description": "string",
    "description_extended": "string",
    "updated": "integer",
    "sentiment": "string",
    "aggressor_ind": "string (float)",
    "option_symbol": "string (SPY190826P00292000)",
    "underlying_type": "string",
    "underlying_price": "string (float)",
    "cost_basis": "string (float)",
    "put_call": "string",
    "strike_price": "string (float)",
    "price": "string (float)",
    "size": "string (integer)",
    "date_expiration": "string (YYYY-MM-DD)",
    "option_activity_type": "string",
    "trade_count": "string (integer)",
    "open_interest": "string (integer)",
    "volume": "string (integer)",
    "bid": "string (float)",
    "ask": "string (float)",
    "midpoint": "string (float)"
  }
]

Models

option-activity: object

PropertyTypeDescription
idstring

Unique ID of this signal shared across all signal types

datestring (YYYY-MM-DD)

The date the signal was created

timestring (HH:MM:SS)

The time the signal was created

tickerstring

Ticker Symbol (F, MSFT, etc...)

descriptionstring

A human readable description of the signal. This description may updated at any time without notice

description_extendedstring

An extended human readable description of the signal that may include exchange restricted fields. This description may updated at any time without notice. Due to its inclusion of restricted fields, description_extended is available based on vendor and exchange agreement.

updatedinteger

Last updated timestamp, UTC.

sentimentstring , x ∈ { BULLISH , BEARISH }

Indicates whether the trade or sweep was bullish or bearish (i.e., how near the bid or ask it was exected at)

aggressor_indstring (float)

0.0 = 100% trades were at the bid, 1.0 = 100% of trades were at the ask. The value can exceed 1.0 or 0.0 because trades can be executed above or below the current bid or ask at the time.

option_symbolstring (SPY190826P00292000)

Option symbol

underlying_typestring , x ∈ { ETF , STOCK }

Security type of the underlying symbol

underlying_pricestring (float)

Price of the underlying security. Field is available based on vendor and exchange agreement.

cost_basisstring (float)

Cost outlay of the entire sweep or block option trade

put_callstring , x ∈ { CALL , PUT }

Indicates PUT or CALL

strike_pricestring (float)

Strike price of the option

pricestring (float)

Last price of a trade, or last price of last trade in a sweep. Field is available based on vendor and exchange agreement.

sizestring (integer)

Total order size (either of the 1 trade, or the sum of trade sizes for a sweep)

date_expirationstring (YYYY-MM-DD)

Expiration date of the option

option_activity_typestring , x ∈ { SWEEP , TRADE }

Type of unusual option.

trade_countstring (integer)

Number of trades involved in the sweep or trade. Always 1 when optionActivityType = TRADE. Always > 1 when optionActivityType = SWEEP

open_intereststring (integer)

Current open interest

volumestring (integer)

Day volume

bidstring (float)

Bid price at the time of trade, or last trade in case of a sweep. Field is available based on vendor and exchange agreement.

askstring (float)

Ask price at the time of trade, or last trade in case of a sweep. Field is available based on vendor and exchange agreement.

midpointstring (float)

Midpoint price at the time of trade, or last trade in case of a sweep

Structure (JSON)
{
  "id": "string",
  "date": "string (YYYY-MM-DD)",
  "time": "string (HH:MM:SS)",
  "ticker": "string",
  "description": "string",
  "description_extended": "string",
  "updated": "integer",
  "sentiment": "string",
  "aggressor_ind": "string (float)",
  "option_symbol": "string (SPY190826P00292000)",
  "underlying_type": "string",
  "underlying_price": "string (float)",
  "cost_basis": "string (float)",
  "put_call": "string",
  "strike_price": "string (float)",
  "price": "string (float)",
  "size": "string (integer)",
  "date_expiration": "string (YYYY-MM-DD)",
  "option_activity_type": "string",
  "trade_count": "string (integer)",
  "open_interest": "string (integer)",
  "volume": "string (integer)",
  "bid": "string (float)",
  "ask": "string (float)",
  "midpoint": "string (float)"
}