# Uuid Generator (`aluminum_jam/uuid-generator`) Actor

The UUID Generator Actor offers a robust solution for generating universally unique identifiers (UUIDs) on demand through Apify's platform. It supports multiple UUID versions, including v1 (timestamp-based), v4 (random), and v5 (namespace-based), catering to a wide of application needs.

- **URL**: https://apify.com/aluminum\_jam/uuid-generator.md
- **Developed by:** [anuj upadhyay](https://apify.com/aluminum_jam) (community)
- **Categories:** Developer tools, Integrations, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## UUID Generator Actor 🔑

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-06f?style=flat-square)](https://apify.com)
[![Python](https://img.shields.io/badge/Python-3.13-blue?style=flat-square)](https://www.python.org/)

> A robust, high-performance Actor for generating universally unique identifiers (UUIDs) in bulk on the Apify platform.

### 🎯 Overview

The **UUID Generator Actor** provides a professional solution for generating RFC-compliant universally unique identifiers at scale. Whether you need a handful of UUIDs for testing or thousands for production data systems, this Actor delivers fast, reliable, and standards-compliant results.

#### Key Features

✨ **Multiple UUID Versions**

- **UUID v1**: Timestamp-based identifiers (includes MAC address and time)
- **UUID v4**: Random/pseudo-random identifiers (most common)
- **UUID v5**: Namespace-based identifiers (deterministic, based on namespace + name)

🚀 **Bulk Generation**

- Generate up to 100,000 UUIDs in a single run
- Optimized for performance and memory efficiency
- Progress tracking and detailed logging

📊 **Flexible Output Formats**

- **JSON**: Structured data with metadata
- **CSV**: Spreadsheet-compatible format
- **Plain Text**: One UUID per line

⚙️ **Customizable Options**

- Uppercase/lowercase formatting
- With or without hyphens
- Optional timestamps and indexing
- Namespace configuration for UUID v5

### 🎬 Quick Start

#### Basic Usage

1. Open the Actor in [Apify Console](https://console.apify.com)
2. Configure your input parameters:
   ```json
   {
     "uuidVersion": "v4",
     "quantity": 100,
     "outputFormat": "json"
   }
   ```
3. Click **Start** and retrieve your UUIDs from the dataset

#### UUID v4 (Random) - Default

Generate 1,000 random UUIDs:

```json
{
  "uuidVersion": "v4",
  "quantity": 1000,
  "outputFormat": "json",
  "includeHyphens": true,
  "includeUppercase": false
}
```

**Output:**

```json
[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "version": "v4"
  },
  {
    "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "version": "v4"
  }
]
```

#### UUID v1 (Timestamp-based)

Generate time-ordered UUIDs with timestamps:

```json
{
  "uuidVersion": "v1",
  "quantity": 50,
  "outputFormat": "json",
  "addTimestamp": true,
  "addIndex": true
}
```

**Output:**

```json
[
  {
    "uuid": "6c84fb90-12c4-11e1-840d-7b25c5ee775a",
    "index": 1,
    "timestamp": "2025-12-28T10:30:45.123456Z",
    "version": "v1"
  }
]
```

#### UUID v5 (Namespace-based)

Generate deterministic UUIDs based on namespace and name:

```json
{
  "uuidVersion": "v5",
  "quantity": 10,
  "namespace": "dns",
  "name": "example.com",
  "outputFormat": "json"
}
```

**Output:**

```json
[
  {
    "uuid": "cfbff0d1-9375-5685-968c-48ce8b15ae17",
    "version": "v5"
  }
]
```

#### Plain Text Output

Generate UUIDs without hyphens in plain text format:

```json
{
  "uuidVersion": "v4",
  "quantity": 5,
  "outputFormat": "txt",
  "includeHyphens": false,
  "includeUppercase": true
}
```

**Output (stored in key-value store):**

```
550E8400E29B41D4A716446655440000
6BA7B8109DAD11D180B400C04FD430C8
F47AC10B58CC4372A5670E02B2C3D479
9B76C58E9A0B4F1E8E9D3C8A6F4E2D1B
3F2504E0D7E911E19A1F0242AC120002
```

### 📋 Input Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `uuidVersion` | String | Yes | `"v4"` | UUID version: `"v1"`, `"v4"`, or `"v5"` |
| `quantity` | Integer | Yes | `10` | Number of UUIDs to generate (1-100,000) |
| `outputFormat` | String | Yes | `"json"` | Output format: `"json"`, `"csv"`, or `"txt"` |
| `namespace` | String | No | `"dns"` | Namespace for v5: `"dns"`, `"url"`, `"oid"`, `"x500"`, or custom UUID |
| `name` | String | Conditional | - | Name string for v5 (required for v5) |
| `includeHyphens` | Boolean | No | `true` | Include hyphens in UUID format |
| `includeUppercase` | Boolean | No | `false` | Convert UUIDs to uppercase |
| `addTimestamp` | Boolean | No | `false` | Include generation timestamp |
| `addIndex` | Boolean | No | `false` | Include sequential index number |

#### Namespace Options for UUID v5

- `dns` - Domain Name System namespace
- `url` - URL namespace
- `oid` - ISO OID namespace
- `x500` - X.500 DN namespace
- Custom UUID string (e.g., `"6ba7b810-9dad-11d1-80b4-00c04fd430c8"`)

### 📤 Output

#### JSON Format (Dataset)

All runs save data to the Apify dataset. JSON format includes structured objects:

```json
[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "version": "v4",
    "index": 1,
    "timestamp": "2025-12-28T10:30:45.123456Z"
  }
]
```

#### CSV Format (Key-Value Store)

CSV output is saved to the key-value store with key `OUTPUT`:

```csv
uuid,version,index,timestamp
550e8400-e29b-41d4-a716-446655440000,v4,1,2025-12-28T10:30:45.123456Z
6ba7b810-9dad-11d1-80b4-00c04fd430c8,v4,2,2025-12-28T10:30:45.123456Z
```

#### Plain Text Format (Key-Value Store)

Plain text output (one UUID per line) is saved to the key-value store:

```
550e8400-e29b-41d4-a716-446655440000
6ba7b810-9dad-11d1-80b4-00c04fd430c8
f47ac10b-58cc-4372-a567-0e02b2c3d479
```

### 🎯 Use Cases

#### Software Development

- Generate unique identifiers for database records
- Create API keys and session tokens
- Test data generation for QA environments

#### Database Administration

- Populate primary key columns
- Generate unique constraint values
- Database migration and testing

#### API Development

- Create unique request IDs for distributed systems
- Generate idempotency keys
- Microservices correlation IDs

#### Testing & QA

- Load testing with unique identifiers
- Automated test data generation
- Performance testing scenarios

#### System Integration

- ETL processes requiring unique identifiers
- Data synchronization across systems
- Event tracking and logging

### 🏗️ Architecture

This Actor is built with:

- **Python 3.13** - Latest Python runtime
- **Apify SDK** - For seamless platform integration
- **UUID Module** - Python's built-in RFC 4122 compliant UUID library

#### Performance Characteristics

- **Speed**: Generates 10,000 UUIDs in ~1-2 seconds
- **Memory**: Efficient batch processing for large quantities
- **Scalability**: Handles up to 100,000 UUIDs per run
- **Reliability**: Built-in error handling and validation

### 🔧 Technical Details

#### UUID Versions Explained

**UUID v1 (Timestamp-based)**

- Format: `time_low-time_mid-time_high_and_version-clock_seq-node`
- Includes: 60-bit timestamp + 48-bit MAC address
- Use case: When temporal ordering is important
- Note: May expose MAC address (privacy consideration)

**UUID v4 (Random)**

- Format: 122 random bits + 6 fixed bits
- Cryptographically strong pseudo-random
- Use case: General purpose, most common
- Collision probability: Extremely low (~1 in 10^36)

**UUID v5 (Namespace + Name)**

- Based on SHA-1 hash of namespace + name
- Deterministic: Same input = same UUID
- Use case: When reproducibility is needed
- Supports standard and custom namespaces

#### RFC Compliance

All generated UUIDs comply with [RFC 4122](https://tools.ietf.org/html/rfc4122) specifications:

- Proper version bits (bits 12-15)
- Proper variant bits (bits 62-63)
- Standard hyphenated format (8-4-4-4-12)

### 🚀 Running Locally

#### Prerequisites

- Python 3.9+
- Apify CLI (`npm install -g apify-cli`)

#### Installation

```bash
## Clone or download the Actor
git clone <your-repo-url>
cd uuid-generator

## Install dependencies
pip install -r requirements.txt

## Run locally
apify run
```

#### Development

```bash
## Login to Apify
apify login

## Test locally
apify run --purge

## Push to Apify platform
apify push
```

### 📊 Examples & Tutorials

#### Example 1: Database Seeding

Generate 5,000 UUIDs for database primary keys:

```json
{
  "uuidVersion": "v4",
  "quantity": 5000,
  "outputFormat": "csv",
  "includeHyphens": true,
  "addIndex": true
}
```

Import the CSV directly into your database:

```sql
LOAD DATA INFILE 'uuids.csv'
INTO TABLE your_table
FIELDS TERMINATED BY ','
(uuid_column, @dummy, id_column);
```

#### Example 2: API Testing

Generate test identifiers with timestamps:

```json
{
  "uuidVersion": "v1",
  "quantity": 1000,
  "outputFormat": "json",
  "addTimestamp": true,
  "addIndex": true
}
```

#### Example 3: Namespace-based IDs

Generate consistent UUIDs for domain names:

```json
{
  "uuidVersion": "v5",
  "quantity": 100,
  "namespace": "dns",
  "name": "api.example.com",
  "outputFormat": "json"
}
```

### 🔗 Integration

#### Using Apify API

```javascript
const ApifyClient = require('apify-client');

const client = new ApifyClient({
    token: 'YOUR_API_TOKEN',
});

const input = {
    uuidVersion: 'v4',
    quantity: 1000,
    outputFormat: 'json',
};

const run = await client.actor('YOUR_USERNAME/uuid-generator').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(`Generated ${items.length} UUIDs`);
```

#### Python Integration

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_API_TOKEN')

run = client.actor('YOUR_USERNAME/uuid-generator').call(
    run_input={
        'uuidVersion': 'v4',
        'quantity': 1000,
        'outputFormat': 'json',
    }
)

dataset = client.dataset(run['defaultDatasetId'])
items = dataset.list_items().items

print(f"Generated {len(items)} UUIDs")
```

### 🤝 Support & Contribution

#### Issues & Feedback

Found a bug or have a feature request? Please open an issue on the [GitHub repository](https://github.com/YOUR_USERNAME/uuid-generator).

#### Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### 📄 License

This Actor is available for use on the Apify platform. See [Apify Terms of Service](https://apify.com/terms-of-service) for details.

### 🏆 Apify 1 Million Challenge

This Actor was developed as part of the [Apify 1 Million Challenge](https://blog.apify.com/one-million-challenge/), demonstrating the power and flexibility of the Apify platform for building scalable automation tools.

### 📚 Resources

- [Apify Documentation](https://docs.apify.com)
- [Apify SDK for Python](https://docs.apify.com/sdk/python)
- [UUID RFC 4122 Specification](https://tools.ietf.org/html/rfc4122)
- [Python UUID Module](https://docs.python.org/3/library/uuid.html)

***

**Built with ❤️ for the Apify community**

# Actor input Schema

## `uuidVersion` (type: `string`):

Select the UUID version to generate:

- **v1** (Timestamp-based): Includes timestamp and MAC address, useful for time-ordered IDs
- **v4** (Random): Cryptographically strong random identifiers, most common choice
- **v5** (Namespace-based): Deterministic UUIDs based on namespace + name, same input = same output

## `quantity` (type: `integer`):

Number of UUIDs to generate (1 to 100,000). Start with a small number for testing, then increase as needed. Performance: ~10,000 UUIDs generated in 1-2 seconds.

## `namespace` (type: `string`):

Namespace for UUID v5 generation. Options: 'dns', 'url', 'oid', 'x500', or a custom UUID string. Only used when UUID version is set to v5.

## `name` (type: `string`):

Name string to generate UUID v5. Required when using UUID v5. Same name + namespace combination will always produce the same UUID. Example: 'example.com', 'user-123', etc.

## `outputFormat` (type: `string`):

Format for exporting UUIDs:

- **json**: Structured data with metadata, saved to dataset
- **csv**: Spreadsheet format, saved to key-value store (also in dataset)
- **txt**: Plain text, one UUID per line, saved to key-value store (also in dataset)

## `includeUppercase` (type: `boolean`):

Convert UUIDs to uppercase (e.g., 550E8400-E29B-41D4-A716-446655440000). Default is lowercase.

## `includeHyphens` (type: `boolean`):

Include hyphens in UUID format. With hyphens: 550e8400-e29b-41d4-a716-446655440000, without: 550e8400e29b41d4a716446655440000

## `addTimestamp` (type: `boolean`):

Include generation timestamp in output (ISO 8601 format). Useful for tracking when UUIDs were created.

## `addIndex` (type: `boolean`):

Include sequential index number in output (1, 2, 3, ...). Useful for tracking UUID order and verification.

## Actor input object example

```json
{
  "uuidVersion": "v4",
  "quantity": 10,
  "namespace": "dns",
  "name": "example.com",
  "outputFormat": "json",
  "includeUppercase": false,
  "includeHyphens": true,
  "addTimestamp": false,
  "addIndex": false
}
```

# Actor output Schema

## `uuids` (type: `string`):

All generated UUIDs in JSON format with metadata

## `csvOutput` (type: `string`):

UUIDs in CSV format (available when outputFormat is set to 'csv')

## `txtOutput` (type: `string`):

UUIDs in plain text format, one per line (available when outputFormat is set to 'txt')

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "quantity": 10,
    "namespace": "dns",
    "name": "example.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("aluminum_jam/uuid-generator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "quantity": 10,
    "namespace": "dns",
    "name": "example.com",
}

# Run the Actor and wait for it to finish
run = client.actor("aluminum_jam/uuid-generator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "quantity": 10,
  "namespace": "dns",
  "name": "example.com"
}' |
apify call aluminum_jam/uuid-generator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aluminum_jam/uuid-generator"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/n07gGm2tnSZez3SdT/builds/4sAeBX7IYNCkbshnd/openapi.json