Items

Get item counts

Returns item counts by state, type or source using the filters of GET /items. Counts every state unless you name one.

GET
/items/stats

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Query parameters

by?string

Grouping axis: state, type or source. Defaults to state.

Value in"state""type""source"
type?string

Only return items of these types and their subtypes: a comma-separated list of up to 10, such as core.note,app.*. A wildcard such as core.* matches every type under that prefix.

state?string

Only count items in these lifecycle states: one state or a comma-separated list, such as active,archived. Without it, every state is counted, as with any.

source?string

Only return items stamped with this source.

tier?string

Only return items in this tier. Omit it or send all for both tiers.

Value in"library""feed""all"
tags?string

Comma-separated tags. Only return items that carry all of them. At most 100 distinct tags, each at most 128 characters.

filter?string

A filter expression. A term naming an edge type, edge[<type>] or backref[<type>], needs read on it; edge[<type>]=<id> also works as a query parameter. status_group matches by status group; properties.<field>.<member>, by a list entry.

beneath?string

An item ID. Only return that item and the items under it by parent-of edges, at any depth, walking only through items you can read. Needs read on parent-of edges.

occurred_after?string

Only return items whose own time (occurred_at, else created_at) is after this time. For the modification time, use updated_after.

Length1 <= length
occurred_before?string

Only return items whose own time (occurred_at, else created_at) is before this time.

Length1 <= length
updated_after?string

Only return items changed at or after this time. Send the latest updated_at you hold, and deduplicate by ID, as items can share an instant. Ordered by updated_at, then ID, ascending, so leave out sort and direction. Purges aren't reported.

Length1 <= length
updated_before?string

Only return items changed before this time. It doesn't change the ordering, so it works with any sort.

Length1 <= length
include?"system"

system counts system.* items too, which are left out by default. A type filter in the system. namespace opts in on its own.

Value in"system"

Response body

About errors

Returns an object that maps each state, type or source to its count.

application/json
  1. response
[key: string]?number
  • validation_error: a query parameter is unknown or invalid, or by is not state, type or source.
  • unknown_type: type is a concrete type that nothing registers.
application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

  • type_not_permitted: your credential reaches no type, or type names a type you can't read with none readable under it.
  • edge_type_not_permitted: the filter has an edge or backref term for an edge type you can't read.
application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X GET 'http://localhost:8600/items/stats'
About errors
{  "acme.contact": 2,  "acme.deal": 2}