Skip to main content
POST/metadata/query

Filter Metadata

Create query. (Data, Queries & Vectors) POST /@:projectSlug/metadata/query.

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
surfaces *string[]

The surfaces to read, at least one.

A storage: surface answers 501.

Together they may return at most 10,000 rows (413 above that).

whereobject[]

Filters; every clause must match.

On a collection surface, one clause per field.

field *string

The field to filter on.

On a collection surface, metadata.<column> for a declared column.

On a telemetry surface, createdAt (with gt, gte, lt, lte) or actorId (with eq).

op *"eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "startsWith" | "endsWith" | "in" | "notIn" | "and" | "or" | "not"

The operator. and, or and not are accepted by the parser but refused by every surface.

A protected (encrypted) column allows only eq with a non-null value, and in.

value *any

The value to compare with. in and notIn take a non-empty array of strings, numbers or booleans (none containing ,, ( or )). eq and neq with null test for null.

Other operators take one string, number or boolean.

One of: string
or: number
or: boolean
or: null
or: any[]
limitinteger

Rows per surface.

Default 100.

A telemetry surface returns at most 200.

cursorany

meta.cursor.next from the previous page.

Only with a single surface.

One of: string
or: null
Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe body is malformed: an unknown field, a wrong type, or an unsupported where operator.
400K9O_UNKNOWN_SURFACEA surface is not collection:<name>, storage:<bucket> or telemetry:<eventType>.
400K9O_METADATA_FIELD_NOT_INDEXEDA field is not a declared metadata field of the surface (ch04 §1.3.1); declare it with PUT /metadata/index/{collection}.
400K9O_INVALID_FILTERA where value is invalid for the column.
401K9O_INVALID_CREDENTIALSThe caller is not authenticated.
403K9O_ACCESS_DENIEDThe caller has no read access to the collection (the record read's own gate).
403K9O_EXTENSION_PERMISSION_DENIEDAn extension token: the Metadata API is not extension-callable yet.
413K9O_QUERY_RESULT_TOO_LARGEThe union of the surfaces' rows exceeds the cross-surface cap.
501K9O_NOT_IMPLEMENTEDThe storage slice is not available yet (object metadata has no query index).
Response body (200)
data *object[]

The matching rows.

A query over several surfaces lists each surface's rows in the order the surfaces were named.

surface *string

The surface label the row came from, as sent.

scope *string

The surface's scope: the collection name, or the audit event type for telemetry.

recordIdstring

The record's id.

Present on collection rows only.

eventIdstring

The audit event's id.

Present on telemetry rows only.

metadata *object

For a collection surface: the record's declared metadata columns (see PUT /metadata/index/{collection}), keyed by column name, with each value as the record read returns it (string, number, boolean, null, or an array or object for array and jsonb columns).

A declared column the record read did not return is absent.

For a telemetry surface: the audit event as GET /audit-log returns it.

meta *any

Request metadata (request id, trace id, timing and cost) plus cursor.next: pass it as cursor to read the next page, or null when there is no next page.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.metadata.filter({})

Showing example in TypeScript

Request example
{
  "surfaces": [
    "string"
  ],
  "where": [
    {
      "field": "string",
      "op": "eq",
      "value": "string"
    }
  ],
  "limit": 0,
  "cursor": "string"
}
Response example (200)
{
  "data": [
    {
      "surface": "string",
      "scope": "string",
      "recordId": "string",
      "eventId": "string"
    }
  ]
}

More in Data, Queries & Vectors