# Polls

Source: https://www.gryz.ai/docs/publishing/polls/
Updated: 2026-11-16

Polls are rolling out. This page describes how they work where polls are turned on for you.

## Answer first [#answer-first]

A poll is a block inside one of your Gryz documents. A document can hold up to 10, each where its question sits in the text. Whoever can open the document can vote, and nobody else can. Your agent can create a poll, read the result and close it, and it asks you before it saves the result as a decision.

## Make a poll [#make-a-poll]

* **A quick poll.** Choose **New poll**, pick a starting point (Pick one, Go/no-go, Prioritize, Confidence 1 to 5, Retro pulse, Quick vote or Pick a date), edit the question and options, and create it. Gryz makes a short document that holds the poll and gives you a link to share. The document is kept off Explore and out of search.
* **A poll in a document you already have.** Choose **Add poll** while you edit a Markdown document. The poll goes in where your cursor is.
* **Ask your agent.** "Add a poll to this doc asking which spec we build" works from Claude, ChatGPT, Cursor or any connected agent. See [Poll tools](/docs/mcp/tools/#poll-tools).

A poll has one question (up to 200 characters) and 2 to 6 options (up to 80 characters each). Options can't repeat and can't hold links.

### Three kinds of poll [#three-kinds-of-poll]

| Kind         | What a voter does                                                     | What the results show                                                                                     |
| ------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Pick one     | Chooses one option                                                    | Votes for each option, and the share of voters                                                            |
| Pick several | Chooses a few options, between the fewest and the most you set        | How many voters picked each option. Shares are of voters, so they can add up to more than 100%            |
| Ranked       | Puts the options in order, first choice first, and can leave some out | Each option's place, its points, its average rank, how many ranked it first and how many ranked it at all |

You choose the kind when you create the poll. The kind and the options can't change once someone has voted, apart from answers voters add.

### How a ranked poll is counted [#how-a-ranked-poll-is-counted]

A ranked poll uses points for each place:

* On each ballot, an option ranked first of 4 gets 3 points, second gets 2, third gets 1 and last gets 0. An option the voter left out gets 0.
* The option with the most points comes first.
* **Ties:** if two options have the same points, the one ranked first by more people wins. If that is level too, the one with the better average rank wins. If they are still level, they show as tied.

To rank, choose **Add** on each option in your order, then move a row with the up and down buttons. It works the same on a phone and from the keyboard.

### Letting voters add their own answer [#letting-voters-add-their-own-answer]

Turn on **Let voters add their own answer** when you create a pick one or pick several poll. Each voter can add one answer of their own, and it becomes an option others can pick, marked **Added by a voter**.

* **An answer that repeats an option** (ignoring capitals and spaces) counts as a pick of that option.
* **Up to 12 options in all,** yours included. At 12, the box goes away.
* **You can hide an added answer.** Choose **Hide** on it. Its votes stop counting, and the other picks on those ballots still count.
* **Added answers go through the same content checks** as published text, and can't hold links.
* **Never on a public document.** If a document becomes public, the box goes away, and answers already added stay.
* Ranked polls don't take added answers, because a growing list would make the points unfair.

## A poll is as private as its document [#a-poll-is-as-private-as-its-document]

A poll has no privacy setting of its own. Gryz works out who can see it and vote from the document, every time.

| Document      | Who sees the poll and votes                                | How a vote is counted                                                                                                   | What a link preview shows                                                          |
| ------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Private       | You and the people you shared the document with, signed in | One per account                                                                                                         | Nothing about the poll                                                             |
| PIN protected | Anyone who entered the PIN                                 | One per browser, or one per account when signed in                                                                      | The question only                                                                  |
| Public        | Anyone with the link                                       | One per browser, or one per account when signed in. Without an account, a quick check that you are a person comes first | The question and options, with results when they are public or the poll has closed |

* **If you change who can see the document, the poll follows at once.** Votes are kept. Counts show only to people who can open the document now.
* **Vote without an account, then sign in,** and your vote moves to your account. It counts once.
* **Nobody sees who voted.** Everyone sees counts only. As the owner you also see how many voters were signed in and how many were not.
* **You can change your vote** until the poll closes.

For how each kind of document is shared, see [Visibility and sharing](/docs/publishing/visibility-and-sharing/).

### Polls in a company document [#polls-in-a-company-document]

A company document's poll follows the company's rules, and nothing more is allowed than the company allows for its documents.

| Company document                    | Who sees the poll and votes                                                                     | How a vote is counted                                                                            | What a link preview shows                                                          |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| Company only                        | Members who can open the document, signed in (with two-step sign-in if the company asks for it) | One per account                                                                                  | Nothing about the poll                                                             |
| Shared with a protected link        | Anyone with the link and its password, until the link ends                                      | One per browser, or one per account when signed in                                               | Nothing about the poll                                                             |
| Public, where the company allows it | Anyone with the link                                                                            | One per browser, or one per account when signed in, with the same quick check without an account | The question and options, with results when they are public or the poll has closed |

* **Company documents never have a PIN,** so their polls don't either.
* **Anyone who can edit a company Markdown document can add a poll** from the editor. Company owners and admins can also close a poll and hide an answer a voter added.
* **In a project,** a document's polls show in the project's Catch me up summary: open ones first, then the ones that closed this week, with results only for people who could see them on the poll.
* **No "Make your own poll" and no Gryz mark** on company polls.

## Where a poll sits in a Markdown document [#where-a-poll-sits-in-a-markdown-document]

In a Markdown document a poll is a small block with the poll's id as its only line:

````markdown
```gryz-poll
k3f9x2ab
```
````

* **Move the block** and the poll moves with it.
* **Delete the block** and readers stop seeing the poll. It isn't deleted and its votes are kept, but it takes no new votes. You see it under **Polls not in the text**, with **Put back** and **Delete poll**.
* **The same block twice:** the first shows the poll, and later ones say it is above.
* **A block with an id that isn't a poll of this document** shows nothing to readers.
* **Restore an older version** that holds the block and the poll comes back.

In an HTML document, polls show after the page. There is nothing to place, unless you want the poll to look like part of the page.

## A poll styled to match an HTML page [#a-poll-styled-to-match-an-html-page]

In an HTML document a poll can sit inside the page, with the page's own look. The page marks what a reader clicks, and Gryz does the voting:

```html
<div data-gryz-poll-state="k3f9x2ab">
  <button type="button" data-gryz-poll="k3f9x2ab" data-option="1">Friday <span data-gryz-poll-count="k3f9x2ab" data-option="1"></span></button>
  <button type="button" data-gryz-poll="k3f9x2ab" data-option="2">Saturday <span data-gryz-poll-count="k3f9x2ab" data-option="2"></span></button>
  <p data-gryz-poll-total="k3f9x2ab"></p>
</div>
```

| Attribute                                 | Where it goes                              | What Gryz does                                                              |
| ----------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
| `data-gryz-poll` with `data-option`       | Anything a reader clicks, such as a button | A click opens the Gryz vote box and names that option. Options count from 1 |
| `data-gryz-poll-count` with `data-option` | Where a count shows                        | Sets `data-gryz-count` and `data-gryz-percent`                              |
| `data-gryz-poll-total`                    | Where the number of voters shows           | Sets `data-gryz-total`                                                      |
| `data-gryz-poll-state`                    | A wrapper                                  | Sets `data-gryz-state` to `open`, `closed` or `hidden`                      |

* **The easy way is to ask your agent.** When it creates a poll on an HTML document, Gryz hands it this markup to style and place.
* **The page never casts a vote.** A click only opens the Gryz vote box, where the reader sees the real question and options. The box names the option they clicked but picks nothing: the reader picks an answer in the box, then chooses **Vote**. The options turn on after the box has been still for a moment, so a page can't rush anyone into a vote. A script in the page can't vote, and can't change what the box shows.
* **A poll counts as styled only when the page has a real element for it,** with `data-gryz-poll` and a `data-option` the poll has. A poll id in a comment or a code sample doesn't count, and that poll keeps showing after the page.
* **Show the numbers with CSS,** for example `[data-gryz-count]::after { content: attr(data-gryz-count); }`. Gryz writes the attributes and leaves your text alone.
* **Once the markup is in the page, the poll stops showing after it.** The styled buttons work in the comments view too. The poll shows after the page again only when the page doesn't run scripts (a document published without an account).
* **Pick one and pick several** work this way. A ranked poll always shows after the page, with its own ranking controls. The box to add your own answer is in the Gryz vote box.

### What a styled page can see [#what-a-styled-page-can-see]

A styled page is the author's own HTML and scripts, so here is exactly what it gets from Gryz and what it can work out.

* **What Gryz sends it:** counts for each option and the number of voters, and only when the reader could see them in a normal poll. `hidden` means the poll is open and this reader can't see counts yet. Gryz never sends who voted or what the reader picked.
* **When:** as the page loads, then on a regular refresh (about every 20 seconds, less often when nothing is changing, and not while the tab is in the background). Your own vote shows in the Gryz vote box at once, but the page isn't told because of it. It gets the new counts on the next refresh, like every other reader's page.
* **What it can still work out:** the page's script knows which of its own buttons a reader clicked. Gryz doesn't tell it whether they voted or what they picked in the box, but it can usually work that out from when and how the counts change. A refresh comes about 20 seconds after a vote, so the timing alone suggests this reader voted, and on a quiet poll the one count that went up shows what they picked. With results set to "after you vote", counts appearing tells it this reader has voted. The script never learns an account or a name, but a page can load images from other sites, so its author could record this beside a reader's network address. The author is also the poll's owner and always sees the live counts, so an author who watches closely can match a new vote to a click on their page without waiting for the refresh.
* **If that matters for your poll,** use a normal poll block instead of styled markup, or set results to show after close.

## Who sees the results [#who-sees-the-results]

You choose when you create the poll:

| Setting                      | Before the poll closes              | After it closes                    |
| ---------------------------- | ----------------------------------- | ---------------------------------- |
| After you vote (the default) | You see results once you have voted | Everyone who can open the document |
| Always                       | Everyone who can open the document  | Everyone who can open the document |
| After close                  | Only the owner                      | Everyone who can open the document |
| Owner only                   | Only the owner                      | Only the owner                     |

The owner always sees results. The same rule holds for agents: an agent sees only the counts its person could see on the web.

## After you vote [#after-you-vote]

On a public or PIN poll, once you have voted you can:

* **Say why.** Add a comment to the document that starts with your pick. Without an account, sign in first and you come back to the poll.
* **Share it.** Copy the link, use your phone's share sheet, or open LinkedIn's share page. Only the link is shared.
* **Make your own poll.** It opens "New poll".

Once a poll closes, "Share results" copies the link. On a public poll you can also download the results card, the same image a link preview shows.

Private documents keep the plain poll: results and "Change vote".

### Asking voters their role [#asking-voters-their-role]

On a public poll you can tick "Ask voters their role". Voters can say if they are a PM, in engineering, in design, a founder or something else, or skip it. The results then show the top pick for each role, but only once 5 voters have given that role, so nobody can work out how a small group voted. Nobody sees who gave which role.

## Closing a poll [#closing-a-poll]

A poll closes when the first of these happens:

* **You close it.** Choose **Close poll** and confirm. Nobody can vote after that.
* **Its close time passes.** Set one when you create the poll: in 1 hour, end of today, in 1 day, in 3 days, in 1 week, or a time you pick. Voters see it in their own local time with a countdown.
* **It reaches a number of votes.** Set "close after" to between 2 and 10,000 votes.
* **Its document expires.** A poll can't outlive its document. Deleting the document deletes the poll.
* **Your agent closes it** because you asked.

Once a poll is closed, late votes are refused, and the block shows the final results with a line such as "Most votes: Spec B (5 of 8)", "Tie between Spec A and Spec B (3 each)" or, for a ranked poll, "Ranked first overall: Spec B".

### Who is told when a poll closes [#who-is-told-when-a-poll-closes]

* **You** get a notice in Gryz and an email.
* **People who voted while signed in** get a notice in Gryz.
* **People who voted without an account** aren't told, because Gryz has no way to reach them.

A poll you close, or one that reaches its number of votes, sends notices right away. A poll that closes at its close time, or because its document expired, sends them within about 15 minutes. Each close sends its notices once.

### Extend or reopen a poll [#extend-or-reopen-a-poll]

* **Extend.** On an open poll, choose **Extend** and pick a later close time. A poll can't outlive its document, so a time after the document expires closes the poll when the document expires, and Gryz tells you so.
* **Reopen.** On a closed poll, choose **Reopen**. Every vote is kept, and people can change their votes again. You can set a new close time.
  * You can reopen a poll **once**.
  * You can't reopen it after a decision was saved from its document since it closed, because that decision may rest on the result.
  * The poll shows "Reopened on" with the date.

Extending and reopening are on the web only. An agent can't do either.

## Polls and your agent [#polls-and-your-agent]

With Gryz connected, your agent can:

* **Create a poll** when you ask or agree, in a new short private document or in a document you own: pick one, pick several or ranked, with or without answers voters add. A new short document can go straight into one of your projects
* **List your polls** and **read one**, with the counts you could see yourself. A list can be just one project's polls
* **Close a poll** when you say so
* **Do the same in your company,** on a company connection or by naming the company on a connection that reaches it. Creating and closing need write access there. An app that can only read or only suggest changes can still read polls

In the Skill Library, the **Decision poll** skill teaches an agent to find the open choices in a document, write neutral questions, show you the drafts and create the polls once you say yes.

An agent never votes. When a poll closes with a clear result, the agent can tell you what won and offer to save it as a decision, with the document as its source. When the document is in a project, the decision is saved to that project. It asks first and saves nothing on its own. A tie or a poll with no votes gets a plain line instead.

Ask your agent "how do I use polls?" and it calls `agent_onboarding` with `{ "focus": "polls" }`. See [Set up Gryz for your AI agent](/docs/getting-started/agents/).

## Limits [#limits]

* 10 polls in a document, and 20 open polls per person
* 10 new polls an hour (5 on an account's first day)
* Votes are limited per voter and per browser, so one person can't flood a poll
* One added answer per voter, and 20 added answers an hour on one poll
* Poll questions and options go through the same content checks as published documents
* Closed results become part of the document in Gryz search, for people who can open it. Open polls and results only the owner sees are never added

## Related reading [#related-reading]

* [Visibility and sharing](/docs/publishing/visibility-and-sharing/)
* [Expiry and retention](/docs/publishing/expiry-and-retention/)
* [MCP tools reference](/docs/mcp/tools/#poll-tools)
