Getting Started in Python

Python client and command line tool for Blackfynn.


The Python client is compatible with Python 2.7 and 3.4-3.7.

$ pip install -U blackfynn



In order to conect to Blackfynn using any client, first you must Generate an API token & secret. Once you have generated your API keys, don’t close your browser window until you have used your keys in the following steps.

To create a configuration profile, run bf profile create from the command line:

$ bf profile create

When prompted, give your profile a unique name, or press enter to name your profile default:

Profile name [default]: my_profile

When prompted, paste in your new API key (also called a token) and press enter:

API token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Now paste in the API secret key and press enter:

API secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Finally, enter y to set this profile as the default profile:

Would you like to set 'my_profile' as default (Y/n)? y
Default profile: my_profile

To verify that your profile was set up correctly, run bf status:

$ bf status

Active profile:

Blackfynn environment:
  User          : <your email>
  Organization  : <your organization>
  API Location  :
  Streaming API :

Using this technique you can add multiple connection profiles belonging to different organizations.

Basic Usage

Import and Initialize


If you are using Python 2.7 it is highly recommended that you add from __future__ import print_function to the top of your scripts. This will allow you to easily use Python 3 in the future.

from blackfynn import Blackfynn

bf = Blackfynn()

This will use your default profile to establish a connection. Alternatively, you may want to specify a profile explicitly by name:

bf = Blackfynn('my_profile')

Where my_profile is an existing profile.

Basic Operations

Get your datasets:

# print your available datasets
for ds in bf.datasets():
    print(" Found a dataset: ",

# grab some dataset by name
ds1 = bf.get_dataset('my dataset 1')

# list items inside dataset (first level)

Upload some files into your dataset:


Get a data package:

# use ID to get a package
pkg = bf.get('N:package:1234-1234-1234-1235')

Rename it & add some properties: = "My new package name"
pkg.set_property('Temperature', 83.0)

Uploading files


You must upload files into a Dataset or Collection.

You can upload using the .upload() methods provided on Dataset and Collection objects:

# upload a file into a dataset (ds)

Retrieving data

Let’s say you grab a TimeSeries package:

ts = bf.get('N:package:your-timeseries-id')

You can get the first minute of data in 1-second chunks:

for chunk in ts.get_data_iter(chunk_size='1s', length='1m'):
    # do something with data (pandas Dataframe)
    print("Mean values =", chunk.mean())

You can do the same thing for a single channel:

channel = ts.channels[0]
for chunk in channel.get_data_iter(chunk_size='5s', length='10m'):
    # do something with data (pandas Series)
    print("Max value =", chunk.max())