Data sources
Connect external data — APIs, databases, spreadsheets, RSS, file uploads — to your widgets.
A data source is a connection to data outside widgets.pro. Once created, any widget on any of your dashboards can bind to it. Each fetch produces a data record (dr_) that widgets render.
Built-in source types
| Type | Use it for |
|---|---|
| REST API | Any HTTP endpoint that returns JSON |
| GraphQL | A GraphQL endpoint with a query |
| PostgreSQL | Direct read-only queries against a Postgres database |
| Google Sheets | A specific sheet or range from Google Sheets |
| RSS / Atom | Feeds from blogs, news sites, status pages |
| CSV upload | Static CSV files uploaded to your account |
| Manual | Values you enter directly in the widget config |
For pre-built connectors to SaaS tools (GitHub, Linear, Plausible, Stripe), use Integrations instead — they handle OAuth and provide ready-made data sources.
Create a data source
- Open any widget's configuration panel.
- Click the data source picker → Create new.
- Pick the type, fill the connection details (URL, query, credentials).
- Set a refresh interval.
- Save.
The source becomes available across all your dashboards. You can also manage sources directly under Settings → Data sources.
Authentication
Sources that need credentials (API tokens, database passwords, OAuth tokens) store them encrypted at rest. They're never returned to the client; only their existence is shown in the UI.
You can reference environment-style variables in headers and URLs — they resolve from your account's stored secrets:
Authorization: Bearer ${env.GITHUB_TOKEN}Refresh policies
| Mode | What happens |
|---|---|
| Poll | The client refetches at a fixed interval (e.g. every 30 seconds) |
| Push | The server pushes updates over WebSocket as soon as new data arrives |
| Manual | The viewer triggers a refresh by clicking the refresh button on the widget |
Pick Poll for most cases. Use Push for real-time data that changes frequently (live metrics, chat). Use Manual for expensive queries you don't want to run unprompted.
Data records
Each successful fetch produces a dr_-prefixed data record stored in your account. Widgets reference the latest record. You can browse historical records in the data source detail page — useful for debugging or building widgets that show trends across fetches.
Programmatic access
You can also create and update data sources via the GraphQL API — useful for provisioning dashboards from CI/CD or syncing sources from another system.