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

# Time Range Blueprint

> Track elapsed time for compute, serverless functions, containers, and background jobs, and bill customers for runtime in Dodo Payments.

The Time Range Blueprint sends a usage event to Dodo Payments with how long a resource ran for a customer, in milliseconds, seconds, or minutes. A **Sum** meter over that duration adds up each customer's runtime, so you can bill for compute time. The blueprint ships in the `@dodopayments/ingestion-blueprints` npm package as `trackTimeRange()`.

## Use Cases

The Time Range Blueprint fits these scenarios:

<CardGroup cols={2}>
  <Card title="Serverless Functions" icon="function">
    Bill based on function execution time and memory usage.
  </Card>

  <Card title="Container Runtime" icon="container-storage">
    Track container running time for usage-based billing.
  </Card>

  <Card title="Compute Instances" icon="server">
    Monitor VM runtime and charge by the minute or hour.
  </Card>

  <Card title="Background Jobs" icon="briefcase">
    Track processing time for data exports, reports, and batch jobs.
  </Card>
</CardGroup>

<Info>
  Use it to bill for compute time, function execution duration, container runtime, or any other time-based usage.
</Info>

## Quick Start

To track runtime, install the package, create a meter, and send the duration each time a resource finishes running.

<Steps>
  <Step title="Install the SDK">
    Install the Dodo Payments Ingestion Blueprints package:

    ```bash theme={null}
    npm install @dodopayments/ingestion-blueprints
    ```
  </Step>

  <Step title="Get Your API Keys">
    Create a Dodo Payments API key under **Developer → API Keys** in the [Dodo Payments dashboard](https://app.dodopayments.com/developer/api-keys), and store it in the `DODO_PAYMENTS_API_KEY` environment variable. Use a test mode key while you build. A test mode key works only with `test_mode`.
  </Step>

  <Step title="Create a Meter">
    In the [Dodo Payments dashboard](https://app.dodopayments.com/), go to **Products → Meters** and click **Create Meter**. Set these fields:

    * **Meter Name**: a descriptive name, such as `Compute Time`.
    * **Event Name**: `time_range_usage`, or a name you choose. It must match `eventName` in your code exactly (case-sensitive). The examples in the next step use a separate event name for each resource type, such as `function_execution`, so each one needs its own meter.
    * **Aggregation Type**: **Sum**, to add up the total duration.
    * **Over Property**: the duration key you send: `durationSeconds`, `durationMinutes`, or `durationMs`.
    * **Measurement Unit**: the unit shown on invoices, such as `seconds`.
  </Step>

  <Step title="Track Time Usage">
    Measure how long the work ran, then call `trackTimeRange()` with the duration in the unit your meter uses:

    <CodeGroup>
      ```javascript Serverless Functions theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'function_execution'
      });

      // Track function execution time
      const startTime = Date.now();

      // Execute your function (example: image processing)
      const result = await yourImageProcessingLogic();

      const durationMs = Date.now() - startTime;

      await trackTimeRange(ingestion, {
        customerId: 'cus_123',
        durationMs: durationMs
      });
      ```

      ```javascript Container Runtime theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'container_runtime'
      });

      // Track container runtime in seconds
      await trackTimeRange(ingestion, {
        customerId: 'cus_456',
        durationSeconds: 120
      });
      ```

      ```javascript VM Instance Runtime theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'vm_runtime'
      });

      // Track VM runtime in minutes
      await trackTimeRange(ingestion, {
        customerId: 'cus_789',
        durationMinutes: 60
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

## Configuration

### Ingestion Configuration

Pass these options to `new Ingestion()`:

<ParamField path="apiKey" type="string" required>
  Your Dodo Payments API key from the dashboard.
</ParamField>

<ParamField path="environment" type="string">
  Environment mode: `test_mode` or `live_mode`. Defaults to `test_mode`. The Dodo Payments SDKs default to `live_mode` instead, so set `live_mode` explicitly in production.
</ParamField>

<ParamField path="eventName" type="string" required>
  Event name that matches your meter's **Event Name** (case-sensitive).
</ParamField>

### Track Time Range Options

Pass these options to `trackTimeRange()`. Each duration you pass is sent as a metadata key with the same name.

<ParamField path="customerId" type="string" required>
  The Dodo Payments customer ID to bill for the runtime, for example `cus_123`.
</ParamField>

<ParamField path="durationMs" type="number">
  Duration in milliseconds. Use for sub-second precision.
</ParamField>

<ParamField path="durationSeconds" type="number">
  Duration in seconds. Most common for function execution and short tasks.
</ParamField>

<ParamField path="durationMinutes" type="number">
  Duration in minutes. Useful for longer-running resources like VMs.
</ParamField>

<ParamField path="metadata" type="object">
  Optional metadata about the resource, such as CPU, memory, or region. Each value must be a string, number, or boolean.
</ParamField>

## Best Practices

<Tip>
  **Choose the Right Unit**: Use milliseconds for short operations, seconds for functions, and minutes for longer-running resources.
</Tip>

A meter sums only the key that its **Over Property** names, so send the duration in the same unit every time.

<Warning>
  **Accurate Timing**: Use `Date.now()` or `performance.now()` for accurate time tracking, especially for serverless functions.
</Warning>


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