> ## 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="str" required>
  The key to of the stream.
</ParamField>

<ParamField body="id" type="str | *" 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="data" type="Dict[str, Any]" required>
  Key-value data to be appended to the stream.
</ParamField>

<ParamField body="maxlen" type="int">
  The maximum number of entries to keep in the stream. Mutually exclusive with `minid`.
</ParamField>

<ParamField body="approximate_trim" type="bool" default="True">
  Use approximate trimming (more efficient). When `True`, Redis may keep slightly more entries than specified. Defaults to `True`.
</ParamField>

<ParamField body="nomkstream" type="bool" default="False">
  Prevent creating the stream if it does not exist. Defaults to `False`.
</ParamField>

<ParamField body="minid" type="str">
  The minimum ID to keep. Entries with IDs lower than this will be removed. Mutually exclusive with `maxlen`.
</ParamField>

<ParamField body="limit" type="int">
  Limit how many entries will be trimmed at most (only valid with approximate trimming).
</ParamField>

## Response

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

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

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

  ```py Approximate trim with maxlen theme={"system"}
  redis.xadd("mystream", "*", {"log_level": "error", "message": "Database connection failed"}, maxlen=100)
  ```

  ```py Auto Sequence Number (Redis 8+) theme={"system"}
  import time

  # Specify millisecond timestamp, let Redis generate sequence number
  ms = int(time.time() * 1000)
  id1 = redis.xadd("mystream", f"{ms}-*", {"event": "login", "user": "john"})
  print(id1)  # e.g., "1769347235123-0"

  # Multiple entries with same ms but different sequence numbers
  id2 = redis.xadd("mystream", f"{ms}-*", {"event": "logout", "user": "john"})
  print(id2)  # e.g., "1769347235123-1"
  ```

  ```py Precise Timestamp Control theme={"system"}
  # Use auto sequence for precise timestamp control
  timestamp = 1634567890123
  result = redis.xadd(
      "events",
      f"{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