/roles

Get government role definitions

Returns available government role definitions with metadata and filtering options.

Parameters

name	type	required	description
levelquery	federal \| state \| local	—	Filter by government level
branchquery	legislative \| executive \| judicial	—	Filter by government branch
activequery	booleandefault true	—	Filter by active status
pagequery	integerdefault 1	—	Page number for pagination
limitquery	integerdefault 50	—	Number of items per page

Example

curl

curl "https://civiclens.io/api/v1/roles?level=federal&limit=5"

200 response

{
  "data": [
    {
      "id": "us-federal-acting-attorney-general",
      "name": "Acting Attorney General",
      "level": "federal",
      "description": "Officeholders in the federal executive branch.",
      "active": true,
      "government": {
        "country": "us",
        "level": "federal",
        "branch": "executive"
      },
      "memberCount": 1
    },
    {
      "id": "us-federal-acting-director-of-national-intelligence",
      "name": "Acting Director of National Intelligence",
      "level": "federal",
      "description": "Officeholders in the federal executive branch.",
      "active": true,
      "government": {
        "country": "us",
        "level": "federal",
        "branch": "executive"
      },
      "memberCount": 1
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 131,
    "hasMore": true
  },
  "meta": {
    "lastUpdated": "2026-09-15T21:33:48.242Z",
    "filters": {
      "level": "federal"
    }
  }
}

A live response, trimmed to the first records. sourceUrl values are shown redacted in documentation; the API returns the full value.

Responses

200List of government roles

400Bad request - invalid parameters

500Internal server error

Try it

PlaygroundLive responses from the real API

endpoint

query

curl

curl "https://civiclens.io/api/v1/roles?level=federal&limit=5"