id as shape when you run the tool.
Shapes are free, a shaped run counts as one run, and only you can see and use your shapes.
Make a shape
outcome is one of:
saved: the shape, with itsid, and apreviewof its result for a made-up result of the tool.needs_tool_change: the tool doesn’t return the data you asked for (missing). Ask for it withchange_website_tool(POST /v1/tools/{id}/changes), then make the shape.not_possible: no shape can do it, such as one needing the time or other pages of results.not_written: Pomerado’s code didn’t pass its checks;findingssays why. Try saying it another way.
shape_id to create_shape, or send PATCH /v1/shapes/{id} with request, name or both. Each change is a new version; GET /v1/shapes/{id} lists the last 100, and POST /v1/shapes/{id}/restore makes an earlier one current again.
Run with a shape
Addshape beside tool_id and input on run_read_only_website_tool, run_website_tool or the REST run routes. The run’s result comes in the shape’s form, and paging fields such as next_cursor are copied onto it, so you page as before. The job’s shape says what happened:
status: "applied": the result is in the shape’s form.status: "skipped": the result is the tool’s own, andreasonsays why. A shape that breaks never fails the run.new_fields: fields the tool returns now that your shape leaves out.messagesays how to add them.
New fields
Tools gain fields over time. A shape leaves them out unless you asked it to keep everything, so your form stays the same. A shape that keeps everything still replaces a new field with its own field of the same name, so that new field counts as left out too. The tool’sshapes, each shape and each shaped run list the new fields, and the Dashboard’s Shapes dialog offers to add them.
Change requests that only reshape
A requested change that only asks for the same data in another form is answered with a shape instead of a tool change: the change’s job succeeds at once, uncharged, withbuild.change.shape naming the shape saved for you. A change that also needs new data goes on as a tool change, and its reshaping part is saved as a shape beside it.