Skip to main content

​
Overview

The createClient() function creates a new instance of the low-level TinybirdClient for interacting with the Tinybird API. For a typed client experience with full TypeScript inference based on your schema definitions, use the Tinybird class instead.

​
Usage

import { createClient } from '@tinybirdco/sdk';

const client = createClient({
  baseUrl: process.env.TINYBIRD_URL,
  token: process.env.TINYBIRD_TOKEN,
});

​
Parameters

​
config
ClientConfig
required
Client configuration object

​
ClientConfig

​
baseUrl
string
required
Tinybird API base URLExamples:
  • 'https://api.tinybird.co' (EU region)
  • 'https://api.us-east.tinybird.co' (US region)
​
token
string
required
API token for authentication. Typically loaded from environment variables.
token: process.env.TINYBIRD_TOKEN
​
fetch
typeof fetch
Custom fetch implementation. Defaults to global fetch if not provided.Useful for:
  • Custom retry logic
  • Request interceptors
  • Testing with mocked responses
​
timeout
number
Default timeout in milliseconds for all requests. Can be overridden per-request.
timeout: 30000 // 30 seconds
​
devMode
boolean
Enable development mode to automatically use branch tokens when on a feature branch.When enabled, the client will:
  • Detect the current git branch
  • Use the corresponding Tinybird branch token instead of the workspace token
  • Automatically create branches if they don’t exist
Default: false
devMode: process.env.NODE_ENV === 'development'
​
configDir
string
Directory to use as the starting point when searching for tinybird.json config.In monorepo setups, set this to the directory containing tinybird.json to ensure the config is found regardless of where the application runs from.
configDir: fileURLToPath(new URL('.', import.meta.url))

​
Return Value

Returns a configured TinybirdClient instance with methods for:
  • Querying pipe endpoints
  • Ingesting events
  • Datasource operations (append, replace, delete, truncate)
  • Token operations (JWT creation)
  • Raw SQL queries

​
Examples

​
Basic Usage

import { createClient } from '@tinybirdco/sdk';

const client = createClient({
  baseUrl: 'https://api.tinybird.co',
  token: process.env.TINYBIRD_TOKEN,
});

// Query a pipe
const result = await client.query('top_pages', {
  start_date: '2024-01-01',
  end_date: '2024-01-31',
});

// Ingest an event
await client.ingest('events', {
  timestamp: '2024-01-15 10:30:00',
  event_type: 'page_view',
});

​
With Development Mode

Automatically use branch tokens during development: 
const client = createClient({
  baseUrl: process.env.TINYBIRD_URL ?? 'https://api.tinybird.co',
  token: process.env.TINYBIRD_TOKEN,
  devMode: process.env.NODE_ENV === 'development',
});

// When on a feature branch, queries and ingestion
// automatically use the branch token
const context = await client.getContext();
console.log(context.branchName); // 'feature_my_branch'

​
With Custom Timeout

const client = createClient({
  baseUrl: 'https://api.tinybird.co',
  token: process.env.TINYBIRD_TOKEN,
  timeout: 60000, // 60 seconds
});

​
With Custom Fetch (Node.js 16 or older)

import fetch from 'node-fetch';

const client = createClient({
  baseUrl: 'https://api.tinybird.co',
  token: process.env.TINYBIRD_TOKEN,
  fetch: fetch as unknown as typeof globalThis.fetch,
});

​
Monorepo Setup

import { fileURLToPath } from 'url';
import { createClient } from '@tinybirdco/sdk';

const client = createClient({
  baseUrl: process.env.TINYBIRD_URL,
  token: process.env.TINYBIRD_TOKEN,
  configDir: fileURLToPath(new URL('.', import.meta.url)),
  devMode: true,
});

TinybirdClient

Core client class documentation

Tinybird (Typed Client)

Type-safe client with schema inference

Query

Query pipe endpoints

Ingest

Ingest data into datasources

Build docs developers (and LLMs) love

Get started for freeTalk to us