paginate results and return metadata

Insufficient docs to answer fully.

Missing information

• Recommended pagination style (offset/limit vs cursor), response schema shape (items + meta), and examples.

See also

• how_do_i/missing-info.md:1