Skip to main content
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"
  }
}
Metadata is returned in all subsequent GET responses for that resource.

​
Validation Rules

ConstraintLimitError Example
Maximum keys50"Metadata can have a maximum of 50 keys. You provided 51 keys."
Key length40 characters"Metadata key \"my_very_long_key_name...\" exceeds 40 character limit."
Key formatNo square brackets"Metadata key \"items[0]\" cannot contain square brackets ([ or ])."
Value length500 characters"Metadata value for key \"description\" exceeds 500 character limit."
Value typeStrings 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. This follows Stripe’s metadata update semantics with merge behavior.

​
Endpoint

PATCH /v1/batches/{batch_id}

​
Update Operations

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"}
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"}
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"}
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: {}
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

OperationRequestResult
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