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

# XADD

> Appends one or more new entries to a stream.

## Arguments

<ParamField body="key" type="string" required>
  The key to of the stream.
</ParamField>

<ParamField body="id" type="string | *" required>
  The stream entry ID. Supports multiple formats:

  * `*`: Fully automatic ID generation (both timestamp and sequence)
  * `<ms>-<seq>`: Explicit ID (e.g., "1526919030474-55")
  * `<ms>-*`: Auto-generate sequence number for the given millisecond timestamp (Redis 8+)
</ParamField>

<ParamField body="entries" type="Record<string, unknown>" required>
  Key-value data to be appended to the stream.
</ParamField>

<ParamField body="options" type="object">
  <Expandable title="properties">
    <ParamField body="nomkStream" type="boolean">
      Prevent creating the stream if it does not exist.
    </ParamField>

    <ParamField body="trim" type="object">
      Trim options for the stream.

      <Expandable title="trim">
        <ParamField body="type" type="'MAXLEN' | 'MINID'" required>
          The trim strategy:

          * `MAXLEN`: Trim based on the maximum number of entries
          * `MINID`: Trim based on the minimum ID
        </ParamField>

        <ParamField body="threshold" type="number | string" required>
          The threshold value for trimming:

          * For `MAXLEN`: The maximum number of entries to keep (number)
          * For `MINID`: The minimum ID to keep (string)
        </ParamField>

        <ParamField body="comparison" type="'~' | '='" required>
          The comparison operator:

          * `~`: Approximate trimming (more efficient)
          * `=`: Exact trimming
        </ParamField>

        <ParamField body="limit" type="number">
          Limit how many entries will be trimmed at most
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField type="string">The ID of the newly added entry.</ResponseField>

<RequestExample>
  ```ts Basic Example theme={"system"}
  const result = await redis.xadd("mystream", "*", { name: "John Doe", age: 30 });
  ```

  ```ts With Custom ID theme={"system"}
  const result = await redis.xadd("mystream", "1634567890123-0", { temperature: 25.5, humidity: 60 });
  ```

  ```ts Trimming with MAXLEN theme={"system"}
  const result = await redis.xadd("mystream", "*", { event: "user_login", user_id: "12345" }, {
    trim: {
      type: "MAXLEN",
      threshold: 1000,
      comparison: "="
    }
  });
  ```

  ```ts Prevent Stream Creation theme={"system"}
  const result = await redis.xadd("existing_stream", "*", { data: "value" }, {
    nomkStream: true
  });
  ```

  ```ts Trimming with MINID theme={"system"}
  const result = await redis.xadd("mystream", "*", { action: "purchase", amount: 99.99 }, {
    trim: {
      type: "MINID",
      threshold: "1634567890000-0",
      comparison: "="
    }
  });
  ```

  ```ts Auto Sequence Number (Redis 8+) theme={"system"}
  // Specify millisecond timestamp, let Redis generate sequence number
  const ms = Date.now();
  const id1 = await redis.xadd("mystream", `${ms}-*`, { event: "login", user: "john" });
  console.log(id1); // e.g., "1769347235123-0"

  // Multiple entries with same ms but different sequence numbers
  const id2 = await redis.xadd("mystream", `${ms}-*`, { event: "logout", user: "john" });
  console.log(id2); // e.g., "1769347235123-1"
  ```

  ```ts Precise Timestamp Control theme={"system"}
  // Use auto sequence for precise timestamp control
  const timestamp = 1634567890123;
  const result = await redis.xadd("events", `${timestamp}-*`, { 
    type: "payment",
    amount: 100.00,
    currency: "USD"
  });
  // Redis generates the sequence number automatically
  ```
</RequestExample>

## ID Format Details

### Automatic ID (`*`)

Fully automatic - Redis generates both the millisecond timestamp and sequence number.

### Explicit ID (`<ms>-<seq>`)

You provide both the millisecond timestamp and sequence number. Example: `"1526919030474-55"`

### Auto Sequence (`<ms>-*`) - Redis 8+

You provide the millisecond timestamp, Redis automatically generates the sequence number. This is useful when you need precise control over the timestamp but want Redis to handle sequence numbering.

**Benefits of Auto Sequence:**

* Precise timestamp control for time-sensitive data
* Automatic sequence management prevents conflicts
* Multiple entries can share the same millisecond with different sequences
* Ideal for batch operations with consistent timestamps