Skip to main content
Version: v5

Output types

Python commands return an OBBject by default. Its results field holds the validated records, and the object carries the provider name, captured warnings, an optional chart, and an extra dictionary. The fields and methods are described in The OBBject envelope. This page covers turning results into other types.

Convert one result​

Call a conversion method on the returned object. The examples use the FRED key from Configure credentials.

from openbb import obb

result = obb.fred.economy.fred_series(symbol="GDP,UNRATE", start_date="2020-01-01")

df = result.to_dataframe()
columns = result.to_dict()
records = result.to_dict(orient="records")
array = result.to_numpy()
text = result.to_llm()

to_dataframe(), also available as to_df(), sets the date column as the index when there is one; pass index=None to keep it as a column, or sort_by and ascending to sort. to_dict() accepts the pandas orientations "dict", "list", "series", "split", "tight", "records", and "index", with "list" as the default. to_numpy() and to_dict() build a DataFrame first without an index, and to_llm() returns a JSON string of records with ISO 8601 dates. Calling any of them on an empty result raises OpenBBError with Results not found.

Set a default for the session​

obb.user.preferences.output_type makes every command call the matching method before returning. The value can also be saved in user_settings.json, as shown in Configure preferences and defaults.

from openbb import obb

obb.user.preferences.output_type = "dataframe"
df = obb.fred.economy.fred_series(symbol="GDP", start_date="2020-01-01")
output_typeMethod calledReturnsNeeds
"OBBject" (default)noneOBBjectnothing extra
"dataframe"to_dataframe()pandas.DataFramepandas
"numpy"to_numpy()numpy.ndarraypandas
"dict"to_dict()dict of column listspandas
"llm"to_llm()strpandas
"polars"to_polars()polars.DataFramepandas, polars, pyarrow
"chart"to_chart()not usable in V5see below

pandas is an optional extra of openbb-core (openbb-core[pandas]), and every V5 provider package depends on it, so it is present once any provider is installed. NumPy is installed with pandas. Polars is not a dependency of any OpenBB package; add it with pip install polars pyarrow, or the conversion raises an OpenBBError that names the missing package and that install command.

OBBject has no to_chart() method, so "chart" passes validation but every command then raises an OpenBBError for the missing attribute. To draw a chart, install openbb-charting, pass chart=True to a command that supports it, and call result.show(); see openbb-charting.

The preference applies only to commands that return an OBBject. A command annotated with another return type, such as obb.news.rss_providers(), which returns a list, raises an OpenBBError when output_type is anything other than "OBBject". Switch back to "OBBject" for those calls.

The preference has no effect on the REST API or the MCP server. REST responses are JSON objects with the id, results, provider, warnings, chart, and extra fields.

Keep the metadata​

Converted outputs contain only results. Everything under extra is dropped, so read it from the OBBject before converting. extra["metadata"] records the arguments, duration in nanoseconds, route, and start time of the call, unless the metadata preference is off. Providers can also attach extra["results_metadata"]; FRED stores the title, units, frequency, seasonal adjustment, and notes of each series under its ID.

from openbb import obb

obb.user.preferences.output_type = "OBBject"
result = obb.fred.economy.fred_series(symbol="GDP")

print(result.extra["results_metadata"]["GDP"]["title"])
df = result.to_dataframe()

Prepare output for LLM tools​

"llm" returns the records as a JSON string, which can be passed straight into a prompt or a tool response. When exposing obb functions as tools, the generated docstrings can also be shortened. Set python_settings in ~/.openbb_platform/system_settings.json; the valid sections are description, parameters, returns, and examples, and docstring_max_length truncates longer docstrings with ....

{
  "python_settings": {
    "docstring_sections": ["description", "examples"],
    "docstring_max_length": 1024
  }
}

Docstrings are generated when the Python Interface is built, so rebuild after changing these settings:

openbb-build

Verify​

Set each type in turn and check what comes back. Without Polars installed, the "polars" line reports the missing dependency.

from openbb import obb

for output_type in ["OBBject", "dataframe", "numpy", "dict", "llm", "polars"]:
    obb.user.preferences.output_type = output_type
    try:
        value = obb.fred.economy.fred_series(symbol="GDP", limit=5)
        print(output_type, type(value).__name__)
    except Exception as error:
        print(output_type, error)

obb.user.preferences.output_type = "OBBject"

On this page