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. Updates use merge behavior.

​
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