# GET: /proposal

## GET: /proposal

### ProposalRequest

The request to the Proposal API can specify various filters, allowing retrieval of proposals by IDs, state, and pagination parameters.

**Request Parameters**

<table><thead><tr><th valign="middle">Type</th><th valign="middle">Key</th><th valign="middle">Description</th></tr></thead><tbody><tr><td valign="middle">uint32</td><td valign="middle"><code>page</code></td><td valign="middle">Page number for pagination</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>limit</code></td><td valign="middle">Number of results per page</td></tr></tbody></table>

#### ProposalResponse

The API returns a list of proposals matching the specified filters, sorted in descending order by proposal ID.

**Response Structure**

<table><thead><tr><th valign="middle">Type</th><th valign="middle">Key</th><th valign="middle">Description</th></tr></thead><tbody><tr><td valign="middle">Struct</td><td valign="middle"><code>metadata</code></td><td valign="middle">Metadata on request (see <strong>ProposalMetadata</strong>)</td></tr><tr><td valign="middle">repeated Proposal</td><td valign="middle"><code>data</code></td><td valign="middle">List of <code>proposals</code> (see Proposal)</td></tr></tbody></table>

### &#x20;ProposalMetadata

Metadata information for pagination and total proposal count.

<table><thead><tr><th valign="middle">Type</th><th valign="middle">Key</th><th valign="middle">Description</th></tr></thead><tbody><tr><td valign="middle">uint32</td><td valign="middle"><code>page</code></td><td valign="middle">Current page number</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>limit</code></td><td valign="middle">Results per page</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>totalItem</code></td><td valign="middle">Total number of proposals available</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>totalPage</code></td><td valign="middle">Total number of pages for given <code>limit</code></td></tr></tbody></table>

#### Proposal Object

A detailed structure representing a governance proposal.

<table><thead><tr><th valign="middle">Type</th><th valign="middle">Key</th><th valign="middle">Description</th></tr></thead><tbody><tr><td valign="middle">uint32</td><td valign="middle"><code>id</code></td><td valign="middle">Unique ID for the proposal</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>description</code></td><td valign="middle">Description of proposed actions</td></tr><tr><td valign="middle">bytes</td><td valign="middle"><code>targets</code></td><td valign="middle">Address receiving calldata</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>values</code></td><td valign="middle">ETH value sent with the transaction</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>signatures</code></td><td valign="middle">Function signature for execution</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>call_datas</code></td><td valign="middle">Encoded function arguments</td></tr><tr><td valign="middle">Struct</td><td valign="middle"><code>params</code></td><td valign="middle">Additional parameters</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>created_Block</code></td><td valign="middle">Block number where proposal was created</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>created_tx_Hash</code></td><td valign="middle">Transaction hash of proposal creation</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>created_timestamp</code></td><td valign="middle">Timestamp of proposal creation</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>start_block</code></td><td valign="middle">Block number when voting starts</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>start_tx_hash</code></td><td valign="middle">Transaction hash of vote initiation</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>start_timestamp</code></td><td valign="middle">Timestamp of vote initiation</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>cancel_block</code></td><td valign="middle">Block number of cancellation (if applicable)</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>cancel_tx_hash</code></td><td valign="middle">Transaction hash of cancellation</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>cancel_timestamp</code></td><td valign="middle">Timestamp of cancellation</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>end_block</code></td><td valign="middle">Block number when voting ends</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>end_tx_hash</code></td><td valign="middle">Transaction hash of vote conclusion</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>end_timestamp</code></td><td valign="middle">Timestamp of vote conclusion</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>queued_block</code></td><td valign="middle">Block number when proposal was queued</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>queued_tx_hash</code></td><td valign="middle">Transaction hash of queueing</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>queued_timestamp</code></td><td valign="middle">Timestamp when proposal was queued</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>executed_block</code></td><td valign="middle">Block number when proposal was executed</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>executed_tx_hash</code></td><td valign="middle">Transaction hash of execution</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>executed_timestamp</code></td><td valign="middle">Timestamp of execution</td></tr><tr><td valign="middle">bytes</td><td valign="middle"><code>for_votes</code></td><td valign="middle">Number of votes in favor</td></tr><tr><td valign="middle">bytes</td><td valign="middle"><code>against_votes</code></td><td valign="middle">Number of votes against</td></tr><tr><td valign="middle">bytes</td><td valign="middle"><code>proposer</code></td><td valign="middle">Address of the proposer</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>eta</code></td><td valign="middle">Estimated execution time</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>forVotes</code></td><td valign="middle">String representation of votes in favor</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>againstVotes</code></td><td valign="middle">String representation of votes against</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>canceled</code></td><td valign="middle">1 if canceled, 0 otherwise</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>executed</code></td><td valign="middle">1 if executed, 0 otherwise</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>state</code></td><td valign="middle">Current proposal state (<code>Pending</code>, <code>Active</code>, <code>Canceled</code>, <code>Defeated</code>, <code>Succeeded</code>, <code>Queued</code>, <code>Expired</code>, <code>Executed</code>)</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>voter_count</code></td><td valign="middle">Total number of voters</td></tr><tr><td valign="middle">Timestamp</td><td valign="middle"><code>created_at</code></td><td valign="middle">Proposal creation timestamp</td></tr><tr><td valign="middle">Timestamp</td><td valign="middle"><code>updated_at</code></td><td valign="middle">Proposal last updated timestamp</td></tr><tr><td valign="middle">uint32</td><td valign="middle"><code>expired_timestamp</code></td><td valign="middle">Timestamp when proposal expires</td></tr><tr><td valign="middle">string</td><td valign="middle"><code>title</code></td><td valign="middle">Proposal title</td></tr></tbody></table>

#### Usage Notes

* Pagination: Use page and limit parameters to navigate large proposal datasets.
* Filtering: Query proposals by state to retrieve active, canceled, or executed proposals.
* Tracking: Monitor proposal progress using `start_block`, `end_block`, and `executed_block` timestamps.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onyx.org/api/get-proposal.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.