Batch Labels

Add or update up to 100 labels across many wallets in a single request. Each item carries its own address; rows with an invalid address are quarantined and reported rather than failing the whole batch.

POST /v0/profiles/labels

cURL

batchLabels

curl --request POST \
  --url https://api.formo.so/v0/profiles/labels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "tag_id": "vip",
    "value": "tier-1"
  },
  {
    "address": "EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV",
    "tag_id": "airdrop_eligible",
    "chain_id": "1"
  }
]
'

200

Example

{
  "successful_rows": 123,
  "quarantined_rows": 123,
  "errors": [
    {
      "index": 123,
      "reason": "<string>",
      "address": "<string>"
    }
  ]
}

Historical (backfilled) labels

Each item extends the single-wallet label schema, so it accepts the same optional timestamp (ISO-8601). When set, that row is recorded at the given time instead of the server’s current time, letting you backfill historical values per wallet in one batch. Label-based retention then evaluates each value at the correct point in time.

curl -sS -X POST \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  -H "Content-Type: application/json" \
  -d '[
    { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "tag_id": "open_interest", "value": "1200", "timestamp": "2026-01-05T00:00:00Z" },
    { "address": "EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV", "tag_id": "open_interest", "value": "800", "timestamp": "2026-01-12T00:00:00Z" }
  ]' \
  "https://api.formo.so/v0/profiles/labels"

timestamp must not be in the future. Unlike an invalid address (which is quarantined for that row only), a future timestamp fails request validation and rejects the whole batch with 400. When omitted, the row is recorded at server time.

Authorizations

Authorization · string · header · required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API Keys.

Body

application/json

Required array length: 1 - 100 elements

tag_id · string · required

Label identifier (lowercased on write). e.g. vip, airdrop_eligible, coinbase.verified_account

address · string · required

Wallet address the label applies to. Literal EVM (0x...) or Solana address only; ENS names are not resolved in batch requests.

value · string

Optional label value (e.g. tier name, country code)

chain_id · string

Optional chain identifier the label applies to

timestamp · string<date-time>

Optional ISO-8601 event-time for the label. When provided, the label is recorded at this time instead of the server's current time; used to backfill historical values (e.g. an open_interest reading from a past week) so label-based retention can evaluate them at the right point in time. Must not be in the future. Defaults to server time when omitted.

Response

200

application/json

Batch processed. Returns counts of forwarded vs quarantined rows, with a per-row errors entry for each quarantined row.

Acknowledgement for a batch write. successful_rows counts rows accepted and forwarded to ingest after a 2xx (ingestion is async/eventually-consistent; there is no follow-up read). quarantined_rows counts rows skipped for an invalid address or no valid keys; errors (omitted when nothing was quarantined) maps each skipped row back to its request index.

successful_rows · integer · required

Number of rows accepted and forwarded to ingest.

quarantined_rows · integer · required

Number of rows skipped (invalid address, or no valid keys).

errors · object[]

One entry per quarantined row. Omitted when quarantined_rows is 0.

Show child attributes