Skip to main content
GET
/
api
/
grid
/
v1
/
accounts
/
{address}
/
proposals
List all proposals for an account
curl --request GET \
  --url https://grid.squads.xyz/api/grid/v1/accounts/{address}/proposals \
  --header 'Authorization: Bearer <token>' \
  --header 'x-grid-environment: <x-grid-environment>'
{
  "data": [
    {
      "approved": [
        "<string>"
      ],
      "cancelled": [
        "<string>"
      ],
      "consensusAccount": "<string>",
      "consensusAccountType": "<string>",
      "proposalAddress": "<string>",
      "rejected": [
        "<string>"
      ],
      "status": "<string>",
      "statusTimestamp": 123,
      "blockTime": "2023-11-07T05:31:56Z",
      "lastModifiedSignature": "<string>",
      "mainAccountAddress": "<string>",
      "settingsAddress": "<string>",
      "transactionIndex": 123
    }
  ],
  "metadata": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}
Lists all proposals associated with a Grid smart account. Use this endpoint to display pending proposals, track voting progress, or audit historical decisions.
The {address} parameter is your smart account address, not a proposal address. You can find this from the account creation response or Get Account.

​
Proposal Status Values

  • Active: Voting in progress, accepts approve or reject votes
  • Approved: Threshold met, ready for execution or can be cancelled
  • Rejected: Rejected by voters (terminal)
  • Cancelled: Cancelled after approval (terminal)
By default, status is client-facing. For proposals that are internally closed on-chain, the API infers terminal outcome when possible (executed, cancelled, or rejected). Use showOnChainStatus=true to return raw on-chain status values (including closed).

​
Pagination

Results are paginated with a default limit of 50 (max 100). Use the cursor from a previous response to fetch the next page: 
// First page
const proposals = await grid.listProposals(accountAddress, { limit: 20 });

// Next page
const nextPage = await grid.listProposals(accountAddress, {
  limit: 20,
  cursor: proposals.nextCursor
});

​
Understanding the Response

Each proposal includes voting state arrays (approved, rejected, cancelled) showing which signers have voted. Use this to:
  • Calculate remaining votes needed: threshold - approved.length
  • Show which signers haven’t voted yet
  • Prevent duplicate vote attempts

Authorizations

​
Authorization
string
header
required

Your Grid API key from the Grid Dashboard

Headers

​
x-grid-environment
string
required

Target Solana environment

Path Parameters

​
address
string
required

Smart account address

Query Parameters

​
status
string

Filter by proposal status

​
limit
integer<int32>

Limit the number of results (default: 50, max: 100)

Required range: x >= 0
​
cursor
string

Pagination cursor

​
showOnChainStatus
boolean

Return raw on-chain proposal status values

Response

Proposals retrieved successfully

​
data
object[]
required
​
metadata
object
required