Add outputs

How to choose which cells a service returns: single result cells, whole ranges as tables, and the title and format that travel with each result.

1:15

What an output is

An output is a cell, or a range of cells, whose value the service returns after it has calculated. Callers get exactly the outputs you define. Every other cell of the workbook, and every formula, stays private.

Add a single cell as an output

1. Open the service on the Configuration (Konfiguration) tab.
2. Click a cell that holds a formula. The box at the bottom of the panel on the right shows its address and the badge OUT.
3. Click Add as Parameter (Als Parameter hinzufügen). The dialog Add Output Parameter (Ausgabe-Parameter hinzufügen) opens.
4. Check the fields and click Add Parameter (Parameter hinzufügen). The output appears under Output Parameters (Ausgabe-Parameter).
5. Click Save (Speichern), then publish; see Publish and republish.

A single cell without a formula is offered as an input, with the badge IN. To return such a value, put a formula that references it into another cell, for example =B2, and add that cell as the output.

Add a range as an output

1. Select the range by dragging over its cells, for example A2:C9. The badge shows OUT; a range is always an output.
2. Click Add as Parameter.
3. The dialog shows the data type Array (Range) (Array (Bereich)), which is fixed for ranges. For a range of several rows it also shows Range Selection (Bereichsauswahl) with the number of rows and columns. If a formula in the range fills several cells by itself, the dialog adds Follows the formula's size. (Folgt der Größe der Formel.)
4. Click Add Parameter, then Save.

The whole range comes back as one output: a table of values, row by row. Use this for a payment schedule, a price list or the result of a formula that fills several cells.

The fields of the dialog

Parameter Info

AI Info

As for inputs, the name and title are suggested from the text label up to four cells to the left of or above the cell; see Add inputs. Advice for the AI texts is in Write good descriptions.

Titles and formats

Each output is returned with three things: its name, its title and its value. If the output has a format, the answer also carries formatString. A range carries the format of each of its columns instead; see Tables as output below.

The value is the stored value of the cell, not the formatted text. A cell that shows 7.25% returns 0.0725 together with "formatString": "0.00%". Web apps and AI assistants use the format to show the value the way your workbook does; your own code can do the same.

The format is taken from the cell when you add the output:

You can change it in Format String (Optional). More on this in Percentages and formats.

Tables as output

A range output returns a list of rows; each row is a list of cell values, from left to right.

{
  "name": "schedule",
  "title": "Payment schedule",
  "value": [
    ["Year", "Interest", "Balance"],
    [1, 7840.5, 193280.1],
    [2, 7566.2, 186285.9]
  ]
}

• Headers. If the header row should be part of the answer, include it in the range. A first row that holds only text above a row with numbers is recognised as the header: the answer then carries "hasHeaderRow": true, and web apps and web snippets show that row as the table's header.
• Empty cells come back as null.
• Error cells come back as the error text, for example "#N/A".

How large the table is

• A plain range has the size you selected. Cells without a value come back as null.
• A range on a formula that fills several cells follows the formula. Formulas such as SEQUENCE, FILTER, SORT or UNIQUE fill as many cells as their result needs, and that number can change with the inputs. If the cell with such a formula lies inside the range, the answer has as many rows and columns as the formulas fill for this call: a repayment plan with one row per year returns 6 rows for 5 years and 16 rows for 15 years, whichever of the two you selected. The dialog shows Follows the formula's size. for such a range. - The table starts at the top left cell of your range. Everything inside your range that holds a value stays, for example a header row above the formula or a totals row below it. Rows and columns at the end of your range that hold nothing are left out. - A formula can only fill empty cells. If a value stands in its way, for example a totals row directly below a list that grows, the cell with the formula shows #SPILL!, in the answer as in Excel. Keep the cells below and to the right of such a formula free. - Select the range so that it includes the cell with the formula. A range that starts below or beside that cell has the size you selected. - A table that follows its formulas returns at most 10,000 cells. Rows beyond that are left out and the output carries "truncated": true. A range you selected larger than that is returned in its selected size.
• Whether a range follows a formula is decided when you publish. After changing the formulas, publish again.

The format of each column

When you publish, the number format of each column is recorded from the first row below the header, or from the first row if there is no header. The answer carries them as columnFormats, one format string per column and "" for a column without a number format:

{
  "name": "schedule",
  "title": "Payment schedule",
  "value": [
    ["Year", "Interest", "Balance"],
    [1, 7840.5, 193280.1],
    [2, 7566.2, 186285.9]
  ],
  "columnFormats": ["", "€#,##0.00", "€#,##0.00"],
  "hasHeaderRow": true
}

The values stay raw numbers. Web apps and web snippets use the formats to show each column the way your workbook does: 7840.5 as €7,840.50. A table that grows keeps the formats of its columns. If you change a number format in the workbook, publish again.

Rules

• Formula cell or range. A single cell becomes an output when it holds a formula. A range of two or more cells is always an output.
• One parameter per cell. A cell that already is a parameter shows Already added (Bereits hinzugefügt), and a selection that overlaps an existing parameter is refused.
• At least one parameter. A service needs at least one input or output before it can be published; see Publish problems.

Change or remove an output

Hover over the output in the list. The pencil opens the dialog, the bin removes the output after a confirmation, the handle on the left changes the order. Outputs are returned in the order of the list. See Rename, reorder and remove parameters.

For developers and agents

The outputs of an answer:

"outputs": [
  { "name": "monthly_payment", "title": "Monthly payment", "value": 1211.96, "formatString": "€#,##0.00" },
  { "name": "total_paid", "title": "Total paid", "value": 290870.4 }
]

• outputs is a list in the order of the panel. With flatten=true the answer also carries result, an object with one key per output name.
• value is a number, a text, true/false, null for an empty cell, a list of rows for a range, or an error text such as "#DIV/0!".
• formatString is present only when the output has a format.
• A range may carry columnFormats (one format string per column), hasHeaderRow and, when it was cut at 10,000 cells, truncated; see Tables as output above.
• All fields of the answer are described in The API response.

FAQ

How do I define what my API returns?

On the Configuration tab, click a cell with a formula, or select a range, and click Add as Parameter. Each output you add is returned with every call.

Can I return a whole table?

Yes. Select the range, including the header row if you want it, and add it as one output. It is returned as a list of rows.

Why does my cell show IN when I want an output?

A single cell without a formula is offered as an input. Put a formula that references it, such as =B2, into another cell and add that cell as the output.

How do I give an output a readable title?

Open the output with the pencil and fill in Original Title, for example "Monthly payment". The title is returned with the value and shown by web apps and AI assistants.

How do I return the result of FILTER or another formula that fills several cells?

Select a range that includes the cell with the formula, and the header row above it if you want it, and add it as one output. The answer then has as many rows as the formula fills for each call; see How large the table is above.

Can I rename an output without changing the workbook?

Yes. The name and title belong to the parameter, not to the cell. Open the output with the pencil and change them; callers then find the result under the new name.

How many outputs can I have?

There is no fixed number in the panel. Return what callers need; large range outputs make every answer larger.

What do callers see if an output cell has an error?

The output's value is the error text, for example "#DIV/0!". Wrap the formula in IFERROR to return a fallback value instead.

What is the Presentation Hint for?

It tells an AI assistant how to present this result to its user, for example "Format as currency with 2 decimals". You find it in the output's dialog under AI Info.

As an agent, how do I read one result?

Find the entry in outputs whose name you need and read its value, or call with flatten=true and read result.<name>. Use formatString, when present, to present the number.