server.GenericActionCtx

A set of services for use within Convex action functions.

The action context is passed as the first argument to any Convex action run on the server. Actions can call external APIs and use Node.js libraries, but do not have direct database access (ctx.db is not available). Use ctx.runQuery and ctx.runMutation to interact with the database.

You should generally use the ActionCtx type from "./_generated/server".

Example

import { action } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";

export const processPayment = action({
  args: { orderId: v.id("orders"), amount: v.number() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // Read data via ctx.runQuery:
    const order = await ctx.runQuery(internal.orders.get, { id: args.orderId });

    // Call external API:
    const result = await fetch("https://api.stripe.com/v1/charges", { ... });

    // Write results back via ctx.runMutation:
    await ctx.runMutation(internal.orders.markPaid, { id: args.orderId });

    return null;
  },
});

Common mistake: ctx.db is not available in actions. Do not try to access it, use ctx.runQuery and ctx.runMutation instead.

scheduler​

• scheduler: Scheduler

A utility for scheduling Convex functions to run in the future.

Defined in​

server/registration.ts:369

auth​

• auth: Auth

Information about the currently authenticated user.

Defined in​

server/registration.ts:374

storage​

• storage: StorageActionWriter

A utility for reading and writing files in storage.

Defined in​

server/registration.ts:379

runQuery​

▸ runQuery<Query>(query, ...args): Promise<FunctionReturnType<Query>>

Run the Convex query with the given name and arguments.

Each runQuery call is a separate read transaction. Consider using an internalQuery to prevent users from calling the query directly.

Example

const user = await ctx.runQuery(internal.users.get, { userId });

Type parameters​

Parameters​

Returns​

Promise<FunctionReturnType<Query>>

A promise of the query's result.

Defined in​

server/registration.ts:318

runMutation​

▸ runMutation<Mutation>(mutation, ...args): Promise<FunctionReturnType<Mutation>>

Run the Convex mutation with the given name and arguments.

Each runMutation call is a separate write transaction. Consider using an internalMutation to prevent users from calling it directly.

Example

await ctx.runMutation(internal.orders.markPaid, { id: orderId });

Type parameters​

Parameters​

Returns​

Promise<FunctionReturnType<Mutation>>

A promise of the mutation's result.

Defined in​

server/registration.ts:338

runAction​

▸ runAction<Action>(action, ...args): Promise<FunctionReturnType<Action>>

Run the Convex action with the given name and arguments.

Important: Only use runAction when you need to cross runtimes (e.g., calling a "use node" action from the default Convex runtime). For code in the same runtime, extract shared logic into a plain TypeScript helper function instead, runAction has significant overhead (separate function call, separate resource allocation).

Consider using an internalAction to prevent users from calling the action directly.

Type parameters​

Parameters​

Returns​

Promise<FunctionReturnType<Action>>

A promise of the action's result.

Defined in​

server/registration.ts:361

vectorSearch​

▸ vectorSearch<TableName, IndexName>(tableName, indexName, query): Promise<{ _id: GenericId<TableName> ; _score: number }[]>

Run a vector search on the given table and index.

Type parameters​

Parameters​

Returns​

Promise<{ _id: GenericId<TableName> ; _score: number }[]>

A promise of IDs and scores for the documents with the nearest vectors

Defined in​

server/registration.ts:391