Convex

Get API Key

Introduction

Convex is a backend platform for building full-stack apps with a reactive database, server functions, and real-time sync. Components let you add isolated, reusable backend capabilities to your app.

The @tavily/convex-tavily component installs Tavily as an isolated Convex component. Your application actions call a typed TavilyClient, which delegates to component actions and keeps TAVILY_API_KEY in typed Convex environment configuration.

What the Tavily component adds

Method	What it does
`tavily.search(ctx, args)`	Search the web with `basic`/`advanced` depth, time range filtering, and image, favicon, and usage options
`tavily.extract(ctx, args)`	Extract clean content from up to 20 URLs, including query-focused chunks, images, and timeout controls

The component is stateless and owns no database tables.

Setup

Step 1: Install the component

Add the package to your Convex app:

npm install @tavily/convex-tavily

Step 2: Register the component

Add the component to convex/convex.config.ts:

import { defineApp } from "convex/server";
import { v } from "convex/values";
import tavily from "@tavily/convex-tavily/convex.config";

const app = defineApp({
  env: {
    TAVILY_API_KEY: v.string(),
  },
});

app.use(tavily, {
  name: "tavily",
  env: {
    TAVILY_API_KEY: app.env.TAVILY_API_KEY,
  },
});

export default app;

Step 3: Set your API key

Store your Tavily API key in your Convex environment:

npx convex env set TAVILY_API_KEY tvly-your-key

Step 4: Call Tavily from an application action

Create an application-owned action that wraps the component. Keeping this wrapper in your app gives you a place to add authentication, authorization, and rate limiting:

import { action } from "./_generated/server";
import { components } from "./_generated/api";
import { TavilyClient } from "@tavily/convex-tavily";
import { v } from "convex/values";

const tavily = new TavilyClient(components.tavily);

export const searchWeb = action({
  args: { query: v.string() },
  handler: async (ctx, args) => {
    return await tavily.search(ctx, {
      query: args.query,
      searchDepth: "advanced",
      maxResults: 5,
      includeAnswer: false,
      includeFavicon: true,
    });
  },
});

Step 5: Verify the component is working

Call your action from your app client with a current-events query, for example:

What were the latest Model Context Protocol announcements?

The request flows from your client through your application action, TavilyClient, and the component to https://api.tavily.com/search, and returns grounded results with sources.

Extract content from known pages

Use tavily.extract to pull clean markdown from specific URLs:

export const extractPages = action({
  args: {
    urls: v.array(v.string()),
    query: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    return await tavily.extract(ctx, {
      urls: args.urls,
      query: args.query,
      chunksPerSource: args.query ? 3 : undefined,
      extractDepth: "advanced",
      format: "markdown",
    });
  },
});

Tavily MCP Server

Keyless Access

Developer

Machine Payments

Partnerships

Integrations

Get API Key

Introduction

What the Tavily component adds

Requirements

Setup

Extract content from known pages

Learn more

Get API Key

​Introduction

​What the Tavily component adds

​Requirements

​Setup

​Extract content from known pages

​Learn more

Introduction

What the Tavily component adds

Requirements

Setup

Extract content from known pages

Learn more