Ready Signal API Documentation – Python (SDK)

This guide shows how to use the readysignal Python package to call the Ready Signal API for listing signals, fetching metadata, retrieving output (as JSON or pandas DataFrames), running Auto Discovery, and handling pagination and status checks.

– API base: https://app.readysignal.com
– PyPI: pip install readysignal
– GitHub repo: https://github.com/rxa-io/readysignal

The Ready Signal API Python library can be found here:
https://pypi.org/project/readysignal/

Download Jupyter Notebook Starter Package

1. Get an Access Token

To use the Ready Signal API, you’ll need an access token to authenticate your requests:

Log in and locate your API credentials
1. Log in to your Ready Signal Account
2. Open an existing Signal or create a new one.
3. Select Output for the Signal
4. In the API Credentials section clip the copy icon next to your access token

That’s it. You will use that token to authenticate your next requests.

2. Install and import

pip install --upgrade readysignal

import os
import readysignal as rs
import pandas as pd

Tip: Store your token securely (e.g., environment variable) rather than hard-coding it

ACCESS_TOKEN = os.getenv("READYSIGNAL_TOKEN") # set this in your shell or .env

2. GET My Signals

Retrieve a list of all signals associated with your Ready Signal account. Each record includes summary information such as configuration, time range, status and output links.

signals = rs.list_signals(ACCESS_TOKEN)
signals # dict with your signals (id, name, status, links, etc.)

Example Output

{    "data": [        {            "id": {signal_id},            "name": "My Signal Name",            "description": "The description of my signal.",            "desired_geo_grain": "State",            "desired_time_grain": "Week",            "start_at": "01/26/2020",            "end_at": "05/31/2020",            "created_at": "06/03/2020",            "updated_at": "06/03/2020",            "deleted_at": null,            "output": {                "json": "https://app.readysignal.com/api/signals/{signal_id}/output?format=json"            },            "links": {                "self": "https://app.readysignal.com/signal/{signal_id}/manage",                "manage": "https://app.readysignal.com/signal/{signal_id}/manage            },            "status": "Ready",            "error_message": ""        }   ], }

3. GET Signal Metadata

Retrieve detailed information about a specific signal ID, including configuration, metadata.

This endpoint is typically used to inspect a signal’s setup and metadata before fetching its output.

signal_id = 1234
signal_meta = rs.get_signal_details(ACCESS_TOKEN, signal_id, optimized= 1) # or optimized=0
signal_meta # dict with config, features (incl. lead/lag), links, status

Parameters

Parameter	Type	Required	Description
ACCESS_TOKEN	string	yes	Your Ready Signal Bearer Token
signal_id	integer	yes	Your Ready Signal Signal ID
optimized	Boolean	Optional	When present (or set to 1), returns optimized signal metadata. Only available for signals generated by auto-discovery (or Market Scout in the GUI) where create_custom_features = 1.

Example Output

{     "data": {         "id": {signal_id},         "name": "Auto-discovery - Unit Sales",         "description": null,         "desired_geo_grain": "Country",         "desired_time_grain": "Month",         "start_at": "01/01/2021",         "end_at": "-",         "created_at": "09/30/2025",         "updated_at": "09/30/2025",         "deleted_at": null,         "features": [             {                 "feature_id": 15515,                 "feature_name": "Merchant Wholesalers, Except Manufacturers Sales Branches and Offices: Nondurable Goods: Farm Product Raw Materials Inventories",                 "export_name": "merchant-wholesalers-except-manufacturers-sales-branches_Lag1",                 "product_name": "Wholesale Trade",                 "provider_name": "U.S. Census Bureau",                 "geo_grain": "Country",                 "date_grain": "Month",                 "data_notes": null,                 "units": "Percent",                 "available_through": "2025-07-31",                 "published_at": "2025-09-10 09:01:24",                 "data_transformations": {                     "lead_lag": -1                 }             }         ],         "output": {             "json": "https://app.readysignal.com/api/signals/{signal_id}/output?format=json"         },         "links": {             "self": "https://app.readysignal.com/api/signal/{signal_id}/manage",             "manage": "https://app.readysignal.com/api/signal/{signal_id}/manage"        },         "status": "Ready",         "error_message": ""     },     "optimized": true }

4. GET My Signal Output

Retrieve the processed output data for a specific signal ID

You can filter by startDate, endDate, limit to the target variable range, and request optimized output (for signals created with Auto Discovery using create_custom_features=1)

Default
rs.get_signal_pandas(access_token, signal_id) #returns pandas dataframe
rs.get_signal(access_token, signal_id) #returns JSON

Optional Parameters
rs.get_signal_pandas(access_token, signal_id, optimized=1, startDate=YYYY-MM-DD, endDate=YYYY-MM-DD, useTargetVariableDates=1) #returns pandas dataframe

Parameters

Parameter	Type	Required	Description
ACCESS_TOKEN	string	yes	Your Ready Signal Bearer Token
signal_id	integer	yes	Your Ready Signal Signal ID
optimized	Boolean	Optional	When present (or set to 1), returns optimized signal output. Only available for signals generated by auto-discovery (or Market Scout in the GUI) where create_custom_features = 1.
startDate	String (YYYY-MM-DD)	Optional	Filters output to data starting on or after this date.
endDate	String (YYYY-MM-DD)	Optional	Filters output to data ending on or before this date.
useTargetVariableDates	Boolean	Optional	When present (or set to 1), limits the output to the date range of the target variable.

Example Return

{        "current_page": 1,        "data": [        {              "start": "2020-01-26",              "end": "2020-02-01",              "state": "Alabama",              "population-rural": "1957932.00000000000000000000"        },        {              "start": "2020-01-26",              "end": "2020-02-01",              "state": "Alaska",              "population-rural": "241338.00000000000000000000"        },        {…},        {              "start": "2020-05-24",              "end": "2020-05-30",              "state": "Puerto Rico",              "population-rural": "232533.00000000000000000000"        }        ],        "first_page_url": "https://app.readysignal.com/api/signals/48/output?page=1",        "from": 1,        "last_page": 1,        "last_page_url": "https://app.readysignal.com/api/signals/48/output?page=1",        "next_page_url": null,        "path": "https://app.readysignal.com/api/signals/48/output",        "per_page": 1000,        "prev_page_url": null,        "to": 936,        "total": 936 }

5. Auto Discovery

Auto Discovery finds external drivers (economic, demographic, weather, etc.) that explain your target series. You can submit data as an array or upload a file. Supported time grains: Month or Day. For monthly, dates must be the first day of the month (YYYY-MM-01). Processing is asynchronous and returns a signal_id immediately.

signal_auto_discover = rs.auto_discover(
access_token=ACCESS_TOKEN,
df=my_target_df, # OR use "file_path='path/to.csv|xlsx'"
filtered_geo_grains="usa", # "usa" | "nonusa" | "all"
create_custom_features=1, # enable optimized signal generation
)


Request Parameters

Parameter	Type	Required	Description
filtered_geo_grains	String	Optional	Filter which geographies are included in discovery. Options: usa, nonusa, or all.
create_custom_features	Boolean	Optional	Enables custom feature generation if set to 1.
data	Array of Objects	Yes (if not file)	Array of data objects containing your time series.
file	Excel or CSV	Yes (if not data)	Excel or CSV file containing your time series.

Data Object

Field	Type	Required	Description
Date	String (YYYY-MM-DD)	Yes	Date of the observation (first day of month).
Value	Numeric	Yes	Value of your target variable (custom feature).

Example Response

{     "message": "Your signal has been created",     "signal_id": 1234 }