> ## Documentation Index
> Fetch the complete documentation index at: https://confect.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata

> Read function, deployment, and request metadata, and inspect transaction usage through Effect services.

Confect provides three services for reading Convex metadata. Import them from `confect/_generated/services`; Confect supplies them automatically in supported handlers and middleware.

| Service | Methods | Available in |
| - | - | - |
| `ExecutionMetadata` | `getFunction()`, `getDeployment()` | Queries, mutations, actions, and HTTP handlers |
| `RequestMetadata` | `get()` | Mutations, actions, and HTTP handlers |
| `TransactionMetadata` | `getMetrics()`, `getSnapshotTs()` | Queries and mutations |

Actions include [Node actions](https://confect.dev/server/node-actions.md). 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.

```ts theme={null}
import * as Effect from "effect/Effect";
import { ExecutionMetadata } from "./_generated/services";

const executionDetails = Effect.gen(function* () {
  const metadata = yield* ExecutionMetadata;
  const fn = yield* metadata.getFunction();
  const deployment = yield* metadata.getDeployment();

  return { functionName: fn.name, deploymentName: deployment.name };
});
```

## 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`.

```ts theme={null}
import * as Effect from "effect/Effect";
import { RequestMetadata } from "./_generated/services";

const requestId = Effect.gen(function* () {
  const metadata = yield* RequestMetadata;
  const request = yield* metadata.get();

  return request.requestId;
});
```

> [!WARNING]
>
> 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.

```ts theme={null}
import * as Effect from "effect/Effect";
import { TransactionMetadata } from "./_generated/services";

const remainingReads = Effect.gen(function* () {
  const transaction = yield* TransactionMetadata;
  const metrics = yield* transaction.getMetrics();

  return metrics.documentsRead.remaining;
});
```

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](https://docs.convex.dev/production/state/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.

```ts theme={null}
import * as Effect from "effect/Effect";
import { TransactionMetadata } from "./_generated/services";

const snapshotTimestamp = Effect.gen(function* () {
  const transaction = yield* TransactionMetadata;
  return yield* transaction.getSnapshotTs();
});
```

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](https://docs.convex.dev/database/advanced/commit-timestamp#snapshot-timestamp).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.