Skip to main content
Confect provides three services for reading Convex metadata. Import them from confect/_generated/services; Confect supplies them automatically in supported handlers and middleware. Actions include Node actions. Each method returns an Effect containing the native Convex metadata value, without transforming its fields. If the underlying Convex call throws or rejects, the Effect fails with a defect rather than a typed error.

Function and deployment metadata

Use ExecutionMetadata to identify the function and deployment running your code. getFunction() returns Convex’s FunctionMetadata, including the function name, component path, type, and visibility. getDeployment() returns DeploymentMetadata, including the deployment name, region, and class.

Request metadata

RequestMetadata.get() returns Convex’s RequestMetadata, including the request ID, IP address, user agent, and scheduled function ID. Nested mutation and action calls inherit the originating request’s metadata. For scheduled jobs and other executions not triggered by an HTTP request, the IP address and user agent are null.
Request metadata can contain the raw authentication token in authToken. Do not log or return the entire metadata object. Select only the fields you need, and treat IP addresses and user agents as sensitive request data.

Transaction metrics

TransactionMetadata.getMetrics() returns Convex’s TransactionMetrics: the used and remaining amounts for limits such as bytes read, documents written, database queries, and scheduled functions. Read these metrics within a query or mutation to inspect its current usage.
Every execution of getMetrics() reads fresh values; the service does not cache them. It only reads metrics and does not start a transaction or change its limits. See Convex’s transaction limits for the limits these metrics describe.

Snapshot timestamp

TransactionMetadata.getSnapshotTs() returns the database snapshot timestamp as a bigint in nanoseconds. The timestamp stays fixed within a transaction and its nested mutations and non-stale queries.
Executing this Effect in a query limits result caching like Date.now(). The timestamp uses the database clock, not wall-clock time; don’t compare it to _creationTime or Date.now(). See Convex’s snapshot timestamp semantics.