Skip to main content
A shape is your own form for one tool’s result: only some fields, renamed, filtered, sorted, grouped, counted or averaged. Say what you want in words. Pomerado writes a small function for it and checks it against every form the tool’s result can take before saving it. Then pass the shape’s 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

It answers in a few seconds and starts no job. outcome is one of:
  • saved: the shape, with its id, and a preview of 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 with change_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; findings says why. Try saying it another way.
To change a shape, pass 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

Add shape 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, and reason says why. A shape that breaks never fails the run.
  • new_fields: fields the tool returns now that your shape leaves out. message says how to add them.
A shape sees only the result, never the run’s input. A website’s refusal always comes as the tool gives it.

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’s shapes, 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, with build.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.