Run a query (I/O API)

This endpoint runs a query across multiple entries in a bucket. Use the returned query ID with the I/O API read endpoint (GET /api/v1/io/:bucket_name/read).

POST

/api/v1/io/:bucket_name/q

Run a query across entries in a bucket

JSON request body

The request body is the same query model as the Entry API, with an additional entries field to select multiple entries:

{
  // Required. Possible values: "QUERY", "REMOVE".
  query_type: 'string';

  // Optional. Specific entries to query or delete records from.
  entries?: 'string[]';

  // Optional. The start UNIX timestamp of the query in microseconds.
  start?: 'integer';

  // Optional. The end UNIX timestamp of the query in microseconds.
  stop?: 'integer';

  // Optional. A conditional query to filter records.
  when?: 'object';

  // Optional. Extension configuration.
  ext?: 'object';

  // Optional. TTL (Time To Live) in seconds for the query.
  ttl?: 'integer';

  // Optional. If true, the query will remain open for continuous data retrieval.
  continuous?: 'boolean';

  // Optional. Return only metadata without record bodies.
  only_metadata?: 'boolean';
}

info

For query_type: "REMOVE", define at least one query parameter (for example entries, start/stop, or when). An empty remove query is rejected.

Entry filtering

• If entries is omitted, the query applies to all entries in the bucket.
• entries supports wildcards:
• ["*"] selects all entries.
• ["prefix-*"] selects all entries with names starting with prefix-.
• You can mix exact names and prefix wildcards (for example ["cam-1", "cam-*", "room/*"]).

Responses

If the query type is QUERY, the API returns a JSON object with the query ID:

{
  id: "integer";
}

If the query type is REMOVE, the API returns a JSON object with the number of removed records:

{
  removed_records: "integer";
}