Field projection

Field projection trims a response down to only the fields you name, with the ?fields= query parameter. Smaller payloads mean faster parsing and less to store — especially when you only need a title, a company name, and a salary from a full role object.

What is the syntax?

Form	Meaning	Example
Comma list	Select several top-level fields	fields=title,location,posted_at
Dot descent	Select a field inside a nested object	fields=company.name,salary.min
[N]	Select one array element by index (0-based)	fields=benefits[0]
[*]	Select all array elements, then optionally descend	fields=benefits[*]

Forms combine freely in one parameter: fields=title,company.name,salary.min,benefits[0].

What does it look like in practice?

Full object trimmed to three scalar paths:

curl "https://api.rolesapi.com/v1/roles/a1b2c3d4e5f60718?fields=title,company.name,salary.min" \
  -H "Authorization: Bearer rk_live_your_key"

{
  "data": {
    "title": "Senior Backend Engineer",
    "company": { "name": "Acme Logistics" },
    "salary": { "min": 140000 }
  },
  "request_id": "req_1e6b0c44"
}

Note the shape is preserved: company.name returns a company object containing only name, not a flattened key.

Array selection:

curl "https://api.rolesapi.com/v1/roles/a1b2c3d4e5f60718?fields=title,benefits[0]" \
  -H "Authorization: Bearer rk_live_your_key"

{
  "data": {
    "title": "Senior Backend Engineer",
    "benefits": ["Health insurance"]
  },
  "request_id": "req_6a2d84f9"
}

On list-shaped responses, such as GET /v1/jobs/{id}/results, the projection applies to each element of data, so fields=job_key,title,company.name returns an array of slim objects.

What does projection apply to?

Projection shapes the data block only. The meta block and request_id are always returned in full, so pagination keeps working regardless of what you project. Requesting a path that does not exist on the object is not an error — the path is simply absent from the output.

Projection also composes with output formats: with ?format=csv, the projected paths become exactly the CSV columns.

Projection changes the size of the response, not its price — a projected role detail still costs 1 credit.