Metadata

Currently available for Batches. Support for scrapes, crawls, maps, and answers is coming soon.

Metadata allows you to attach custom key-value pairs to Olostep resources. This is useful for tracking, filtering, organizing, and storing context alongside your API requests. Metadata follows Stripe’s approach — simple, flexible, and consistent across all endpoints.

Use Cases

Tracking & Organization

Link resources to internal systems with order IDs, customer IDs, or project names.

Filtering & Search

Tag resources for easy retrieval and filtering in your application.

Workflow Context

Store pipeline stage, priority level, or processing instructions.

Audit Trail

Record who initiated a request, timestamps, or version information.

Adding Metadata on Create

Include the metadata parameter when creating a resource:

{
  "url": "https://example.com",
  "metadata": {
    "order_id": "12345",
    "customer_name": "John Doe",
    "priority": "high",
    "internal_ref": "proj-2024-001"
  }
}

import requests

response = requests.post(
    "https://api.olostep.com/v1/batches",
    headers={"Authorization": "Bearer <your_token>"},
    json={
        "items": [{"custom_id": "1", "url": "https://example.com"}],
        "metadata": {
            "project": "q4-analysis",
            "team": "data-ops",
            "priority": "high"
        }
    }
)

const response = await fetch("https://api.olostep.com/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    items: [{ custom_id: "1", url: "https://example.com" }],
    metadata: {
      project: "q4-analysis",
      team: "data-ops",
      priority: "high"
    }
  })
});

Metadata is returned in all subsequent GET responses for that resource.

Validation Rules

Constraint	Limit	Error Example
Maximum keys	50	`"Metadata can have a maximum of 50 keys. You provided 51 keys."`
Key length	40 characters	`"Metadata key \"my_very_long_key_name...\" exceeds 40 character limit."`
Key format	No square brackets	`"Metadata key \"items[0]\" cannot contain square brackets ([ or ])."`
Value length	500 characters	`"Metadata value for key \"description\" exceeds 500 character limit."`
Value type	Strings only	`"Metadata value for key \"count\" must be a string. Got object."`

Type Coercion: Numbers and booleans are automatically converted to strings.

42 → "42"
true → "true"
3.14 → "3.14"

Objects and arrays are rejected.

Updating Metadata (PATCH)

Currently available for: Batches only.Crawls, Scrapes, Maps, and Answers do not yet support updating metadata after creation.

You can update metadata on existing batches using the PATCH endpoint. Updates use merge behavior.

Update Operations

Add new keys

New keys are added while preserving existing ones.

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"new_key": "new_value"}}'

Before: {"project": "alpha"}
After: {"project": "alpha", "new_key": "new_value"}

Update existing keys

Existing keys are overwritten with new values.

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "beta"}}'

Before: {"project": "alpha", "priority": "high"}
After: {"project": "beta", "priority": "high"}

Delete specific keys

Set a key to null or "" (empty string) to delete it.

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"priority": null}}'

Before: {"project": "alpha", "priority": "high"}
After: {"project": "alpha"}

Clear all metadata

Set the entire metadata field to null or "" to remove all keys.

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": null}'

Before: {"project": "alpha", "priority": "high"}
After: {}

Mixed operations

Add, update, and delete keys in a single request.

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "gamma", "new_field": "value", "old_field": null}}'

Before: {"project": "alpha", "old_field": "remove_me"}
After: {"project": "gamma", "new_field": "value"}

PATCH Behavior Summary

Operation	Request	Result
Add key	`{"metadata": {"new": "value"}}`	Key added, others preserved
Update key	`{"metadata": {"existing": "new_value"}}`	Key updated, others preserved
Delete key	`{"metadata": {"key": null}}`	Key removed, others preserved
Delete key	`{"metadata": {"key": ""}}`	Key removed, others preserved
Clear all	`{"metadata": null}`	All keys removed
Clear all	`{"metadata": ""}`	All keys removed
No-op	`{"metadata": {}}`	No changes

Common

Scrapes

Batches

Crawls

Maps

Answers

Search

Monitors

Files

Schedules

Retrieve

Balance & Billing

Use Cases

Tracking & Organization

Filtering & Search

Workflow Context

Audit Trail

Adding Metadata on Create

Validation Rules

Updating Metadata (PATCH)

Update Operations

PATCH Behavior Summary

​Use Cases

Tracking & Organization

Filtering & Search

Workflow Context

Audit Trail

​Adding Metadata on Create

​Validation Rules

​Updating Metadata (PATCH)

​Update Operations

​PATCH Behavior Summary

Use Cases

Adding Metadata on Create

Validation Rules

Updating Metadata (PATCH)

Update Operations

PATCH Behavior Summary