Getting Started with the Tubular API

The Tubular API gives your organization direct access to Tubular data. Using our front-end interface tool we call Query Builder, you can build and schedule data queries that deliver results to external systems – such as data warehouses or BI tools like Tableau – without manual exports.

To get access to the Tubular API added to your product plan, contact your Customer Success Manager or reach out to support@tubularlabs.com.

• What the API Enables
• Query Builder
• Setting Up Your Queries
• Data Streams: Saving and Scheduling Queries
• Understanding Quota
• Rate Limits vs. Quota

What the API Enables

With the Tubular API, your team can:

• Pull creator, video, and trend data directly into external systems on a set schedule
• Deliver data to destinations like AWS S3, which connects to tools such as Tableau, Redshift, BigQuery, and others
• Backfill historical data on first run, then automate recurring pulls going forward
• Access the same data available in the Tubular platform in a format suited for large-scale analysis

Query Builder

Query Builder is the front-end interface environment used to build, preview, and schedule API queries. The general workflow is:

1. Explore and build a query – Use the Query Builder to select an endpoint and configure parameters. Example queries are available throughout the developer documentation with a "Try this query" option to pre-populate the builder with a foundational call structure.
2. Preview results – Run the query to verify the data before saving. Results can be viewed as raw JSON or as a flattened table.
3. Save and schedule – If you’re building a query you want to use regularly, you can give the query a name and set a run schedule (recurring or manual) – this is called a Data Stream in the product, and your Data Streams can all be managed and edited in the API portal. On the first run of a Data Stream, you can define a specific date range to pull historical data; subsequent runs cover the most recent period automatically.

For full implementation and technical details, refer to the Tubular API developer documentation.

The Setup Workflow

Setting up a query for data delivery follows four main stages:

1. Build and test a query using the Query Builder
2. Preview results to verify the data before saving
3. Save the query and configure a run schedule
4. Select a connector destination to deliver data to an external system

Setting up your Queries

The builder has three sections:

• Request Parameters – All available parameters for the selected endpoint. Many fields include a pre-populated list of accepted values.
• Request Preview – Updates in real time as parameters change, showing the API request body as JSON. This can be used as a reference when implementing in code, but is not required to run queries from within the builder.
• Response Preview – Displays results after running the query, either as raw JSON or as a flattened table. This is a preview only and does not constitute a scheduled data delivery.

Note: Running queries/pulling previews in the builder counts against your account's quota. Set reasonable parameters during testing to avoid unintended consumption.

Data Streams: Saving and Scheduling Queries

Once a query looks correct in preview, you can click "Save this query" to configure it for regular delivery, and for easy managing, editing, and downloading of your saved Data Streams. When saving, you can specify:

• Name – A label describing what the query returns
• Schedule – How often the query runs. Set to manually if you want to trigger runs yourself rather than on a recurring basis.
• Connectors – Select one or more destinations. Tubular formats the output to match the selected connector's requirements.
• Export names – A name for the exported file, if you want it to be different from the datastream name.

Understanding Quota

Each Tubular API contract includes a monthly pool of quota units. Units are deducted each time data is returned by the API, based on the number of rows in the response. The number of API calls made does not directly affect quota – a single call returning many rows can consume significant units.

The formula is: units consumed = number of rows × cost per row

Costs vary by data type:

A "row" is defined by a unique combination of dimensions, not by the number of metrics returned. For example: pulling 90 days of data for 10 videos produces 900 rows (one per video per day), regardless of how many metrics are included per row.

Quota is counted monthly. Unused units do not roll over to the following month.

Note: If you are planning a large backfill or high-frequency recurring pulls, review your monthly quota before scheduling. Contact your Customer Success Manager if you need to adjust your plan.

Rate Limits vs. Quota

The API enforces two distinct types of limits:

• Rate limits cap the number of requests per minute. They are the same for all customers and reset automatically every minute. If exceeded, wait a few seconds and retry. You can find details on the rate limits per endpoint type in the Tubular API developer documentation.
• Quota caps the total data returned within a billing period. It varies by subscription and does not reset mid-cycle. If quota is exhausted, contact your Customer Success Manager to increase it or wait until the next billing period.