Load Fitbit data to DuckDB

Fitbit Web API is an interface for accessing and managing data from Fitbit activity trackers, Aria scales, and manual logs. Everything needed to build a working Fitbit → DuckDB pipeline is on this page: the API's base URL, authentication, endpoints, pagination and incremental field — plus a prompt that hands the whole job to your coding agent.

---

Build your Fitbit to DuckDB pipeline

Paste this prompt into Claude, Codex, or Cursor. The agent does the rest.

PromptCopy prompt
Run uvx dlthub-init@latest to build a pipeline from Fitbit to DuckDB and run it on dltHub

That scaffolds a dltHub workspace and installs the dltHub AI harness — the project rules, the secrets-management skill, and the dlt MCP server your agent needs to work safely. From there it reads the Fitbit API, proposes the endpoints to load, then writes, runs and validates the pipeline while you review rather than type. Credentials are inspected through MCP tools, so your agent never reads secrets.toml itself. How the LLM-native workflow works →

Prefer to write it yourself? Every fact the agent uses is below.

---

Fitbit API at a glance

These values come from the Fitbit API reference — the authoritative source if anything here looks out of date.

---

How do I authenticate with the Fitbit API?

Authentication is performed using OAuth 2.0. API requests must include an Authorization header containing a Bearer token: 'Authorization: Bearer <access_token>'.

1. Get your credentials

1. Create/register a Fitbit app in the Fitbit developer portal

• Go to https://dev.fitbit.com/apps/new.
• Fill out the application form.
• Set “Application Type” (commonly “Client” for a traditional app; choose appropriately for your use case).
• Set “Callback URL”/“Redirect URL” (must match exactly what you will use in your OAuth flow).
• Agree to the terms and click Register. 2) Copy your API application identifiers from the app settings
• After registration, record the “OAuth 2.0 Client ID” and “Client Secret” shown on the application details page. If you lose the client secret, you must generate a new one. 3) Obtain an OAuth 2.0 access token (the token you’ll use as the API credential) Option A (common for user data): Authorization Code flow
• First, redirect the user to authorize the app.
• Fitbit then redirects back to your callback URL with an authorization code.
• Exchange that authorization code for tokens by calling POST https://api.fitbit.com/oauth2/token with grant_type=authorization_code, client_id, and (depending on your flow) either your client secret via the required Authorization header or using the flow’s required parameters.
• Fitbit returns an access token and a refresh token. Option B (server-to-server token): Client Credentials flow
• Call POST https://api.fitbit.com/oauth2/token with grant_type=client_credentials using your client_id and client_secret.
• Fitbit authenticates your app and issues an access token. 4) For dlt REST extraction, store the access token as the credential
• For production ingestion into your pipeline, persist the OAuth “access token” securely (and refresh it using the refresh token flow when it expires).
• dlt REST integrations typically use a Bearer access token in the Authorization header.

2. Add them to .dlt/secrets.toml

Copy
[sources.fitbit_source]
# Put your Fitbit OAuth 2.0 access token here (Bearer token)
FITBIT_ACCESS_TOKEN = "your_access_token_here"

dlt reads this file automatically at runtime. With the harness, the setup-secrets skill prompts you for the values and never handles the raw credential in chat. For production, see setting up credentials with dlt.

---

What Fitbit data can I load into DuckDB?

These are the Fitbit endpoints dlt can load into DuckDB:

---

How do I load only new Fitbit records?

Fitbit exposes before_date on 1/user/-/activities/list.json, so dlt can request only the records that changed since the last run. Set it as the cursor_path and dlt tracks the high-water mark for you between runs.

Copy
{"name": "activities_list", "endpoint": {
    "path": "1/user/-/activities/list.json",
    "data_selector": "activities",
    "incremental": {"cursor_path": "before_date", "initial_value": "2024-01-01T00:00:00Z"},
}}

On the first run dlt loads everything from initial_value; on every run after that it requests only what changed and appends with write_disposition="merge" if you set a primary key. See incremental loading.

---

What does the generated Fitbit pipeline look like?

A standard dlt REST API pipeline — the same code you would write by hand, loading POST /oauth2/token and GET /1/user/-/activities/date/{date}.json from the Fitbit API into DuckDB:

Copy
import dlt
from dlt.sources.rest_api import RESTAPIConfig, rest_api_resources

@dlt.source
def fitbit_source(client_id=dlt.secrets.value):
    config: RESTAPIConfig = {
        "client": {
            "base_url": "https://api.fitbit.com",
            "auth": {"type": "bearer", "token": client_id},
        },
        "resources": [
            {"name": "activities_list", "endpoint": {"path": "1/user/-/activities/list.json", "data_selector": "activities"}},
            {"name": "sleep_list", "endpoint": {"path": "1.2/user/-/sleep/list.json", "data_selector": "sleep"}}
        ],
    }
    yield from rest_api_resources(config)


def load_fitbit_to_duckdb() -> None:
    pipeline = dlt.pipeline(
        pipeline_name="fitbit_pipeline",
        destination="duckdb",
        dataset_name="fitbit_data",
    )
    load_info = pipeline.run(fitbit_source())
    print(load_info)


if __name__ == "__main__":
    load_fitbit_to_duckdb()

Run it with python fitbit_pipeline.py. The agent iterates on this until it loads cleanly — you review and approve, rather than write it from scratch.

---

How do I query Fitbit data in DuckDB?

dlt creates one table per resource. Query the loaded data with Python or SQL — or ask your agent to, through the MCP server's execute_sql_query tool.

Python (pandas DataFrame):

Copy
import dlt

data = dlt.pipeline("fitbit_pipeline").dataset()
df = data.sleep_list.df()
print(df.head())

SQL:

Copy
SELECT * FROM fitbit_data.sleep_list LIMIT 10;

See querying your data with dataset and exploring it in marimo notebooks.

---

How do I deploy the Fitbit to DuckDB pipeline in production?

The pipeline runs locally, which is ideal for prototyping and one-off analysis. When you need it on a schedule, monitored on every load, and shared with your team, deploy the same dlt code on the dltHub platform — no infrastructure to maintain. The prompt above already ends with "run it on dltHub", so your agent can take it there directly.

• Deploy & schedule — run the pipeline as a managed job with automatic retries.
• Monitor — observable job queues, alerting, and load metrics for every run.
• Transform — promote raw Fitbit loads into governed, documented models.
• Visualize & share — explore data in notebooks and publish live dashboards instead of static screenshots.

Book a demo →

---

What other destinations can I load Fitbit data to?

dlt loads into any of these — only the destination argument changes:

Set dlt.pipeline(destination="snowflake") and add credentials in .dlt/secrets.toml. On the dltHub platform the same pipeline runs against a managed Iceberg lakehouse. See the full destinations list.

---

Next steps

• Ready for production? Book a demo of the dltHub platform →
• dlt LLM-native workflow docs
• REST API source reference
• Join the dlt community on Slack