---
title: "Let clients ask for only the fields they · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/requests-and-responses/partial-responses
id: API-94
level: Optional
updated: 2026-10-22
build: a2a6bdfed830
tokens: 993
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Let clients ask for only the fields they need

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Requests and responses](https://agentwranglers.se/playbook/api-design/requests-and-responses.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: API-94
- Level: Optional
- Chapter: [Requests and responses](https://agentwranglers.se/playbook/api-design/requests-and-responses.md)
- Rule: When records carry large or costly fields, let clients pick the fields to return with one `fields` parameter. Let them embed related records with one `expand` parameter, capped at one level.
- Check: `GET /products?fields=id,name` returns objects with only those two fields. `GET /products?fields=nope` answers 400. `GET /orders?expand=customer.company` answers 400, since it asks for two levels.
- How: A mobile list that needs a name and a price should not download every description and image. Return all fields when `fields` is missing, so old clients keep working. Answer 400 for an unknown field name rather than ignoring it. Check access for each expanded record as for a direct read, as [Authorise every object](https://agentwranglers.se/playbook/api-design/api-security/object-authorisation.md) says. Expansion multiplies the work of one call, so count each expanded record against the page cap in [Cap the page size](https://agentwranglers.se/playbook/api-design/lists/page-size-limit.md). Keep the field list in the cache key from [Set caching headers on every response](https://agentwranglers.se/playbook/api-design/requests-and-responses/api-cache-headers.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
const PRODUCT_FIELDS = new Set(['id', 'name', 'price', 'description', 'images']);

export function pickFields(record, fieldsParam) {
  if (!fieldsParam) return record;
  const wanted = fieldsParam.split(',');
  const unknown = wanted.filter(field => !PRODUCT_FIELDS.has(field));
  if (unknown.length) throw new BadRequest(`unknown fields: ${unknown.join(', ')}`);
  return Object.fromEntries(wanted.map(field => [field, record[field]]));
}
```

### Python example

```python
PRODUCT_FIELDS = frozenset({"id", "name", "price", "description", "images"})

def pick_fields(record: dict, fields_param: str | None) -> dict:
    if not fields_param:
        return record
    wanted = fields_param.split(",")
    unknown = [field for field in wanted if field not in PRODUCT_FIELDS]
    if unknown:
        raise BadRequest(f"unknown fields: {', '.join(unknown)}")
    return {field: record[field] for field in wanted}
```

## Sources

- [Google AIP-157 Partial responses](https://google.aip.dev/157)

## Related rules

- API-40 [Authorise every object](https://agentwranglers.se/playbook/api-design/api-security/object-authorisation.md) in API design
- API-22 [Cap the page size](https://agentwranglers.se/playbook/api-design/lists/page-size-limit.md) in API design
- API-14 [Set caching headers on every response](https://agentwranglers.se/playbook/api-design/requests-and-responses/api-cache-headers.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/requests-and-responses/partial-responses">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Cap the size of every request body](https://agentwranglers.se/playbook/api-design/requests-and-responses/request-body-limit.md)
- [Requests and responses](https://agentwranglers.se/playbook/api-design/requests-and-responses.md)