Skip to content
PeriplusDocs
Open app
Saved queries and history

Saved queries and history

Save useful SQL and revisit previous runs.

Save a starting point

The bookmark button saves named SQL in your organization’s shared query library. It does not save result rows or execute the query. Saved queries lists the current project's queries. Opening one shows its name, description and SQL, and Run shows its current result rows. When the SQL has positional ? parameters, enter a typed value for each before running. Open in editor copies the SQL into the editor. Search above the list finds any query by name; long lists load more queries as you go.

Editing that SQL does not update the saved query. Save again to create another independent bookmark. You can rename or delete entries in Saved queries; there is no revision history. Agents can search, read, save and organize bookmarks in this same library through MCP. Use descriptive names so teammates and agents can find reusable work.

Projects and descriptions

Every saved query belongs to exactly one project, together with the captures, crawls, pins and schedules of the same piece of work; projects are how you organize queries. Your organization starts with a Default Project, which receives anything saved without a project. Choose a project with the switcher in the sidebar: Saved queries lists that project's queries, and new bookmarks go into it. Move to project… in a query's actions menu moves it. A project only organizes queries: moving one never changes its SQL or how it runs, and every query still reads all of your organization's captures. Only an empty project can be deleted, never the Default Project.

Give queries and projects an optional description written in Markdown: headings, lists, emphasis, code, tables and links render in Saved queries. HTML tags are ignored, images are not loaded, and only web and email links are clickable.

Find something you ran

Recent query history records executed SQL and parameters, with the user and organization that ran them. Opening a history entry loads that SQL into the editor; it does not rerun it automatically.

Detailed execution history is available for 30 days and does not store result rows. Treat SQL and parameters as organization-visible information—do not embed passwords or other secrets in queries.

Pins and schedules stay independent

Creating a pin or schedule from SQL locks in its result at creation. Editing or deleting a saved query does not change an existing pin or schedule.

Save reusable SQL

A saved query is a bookmark, not stored results or a scheduled query. Create saves SQL; get reads it; rename and delete only affect the bookmark.

Python

Python
from periplus_sdk import Client

with Client() as client:
    saved = client.saved_queries.create(
        name="Latest sources",
        sql="SELECT capture_id, url FROM captures ORDER BY observed_at DESC LIMIT 20",
    )
    print(saved.id)

cURL

Shell
curl --fail-with-body "${PERIPLUS_API_URL:-https://api.periplus.dev}/saved-queries" \
  -H "Authorization: Bearer $PERIPLUS_API_KEY" \
  -X POST \
  -H 'Content-Type: application/json' \
  --data '{"name":"Latest sources","sql":"SELECT capture_id, url FROM captures ORDER BY observed_at DESC LIMIT 20"}'

Organize with Python

Python
from periplus_sdk import Client

with Client() as client:
    saved = client.saved_queries.list(search="Latest sources").items[0]
    research = client.projects.create(
        name="Patent research", description="Queries for the **2026 patent** study.")
    client.saved_queries.move(saved.id, project_id=research)
    client.saved_queries.update(saved.id, description="Latest 20 sources. Pass no parameters.",
                                expected_version=client.saved_queries.get(saved.id).version)
    research = client.projects.update(research, description="Archived after the *Q3* review.")
    for project in client.projects.iter():                 # the Default Project first, then by name
        print(project.name, project.item_counts.saved_queries)
    client.saved_queries.list(project_id=research)          # one project's queries

Project updates send the version you last read; when someone else changed the project first, the API returns 409 and you read it again. Passing a Project object uses its version. Saved queries carry a version too, and every edit bumps it. Send it as expected_version when updating so you never overwrite a teammate's change: if the query changed since you read it, the API returns 409 ("This saved query changed since you opened it") and changes nothing, so reload it and apply your edit again. expected_version is optional for saved queries; without it an update applies to the current version. There is no active project: pass project_id on each call that should use one.

Organize with cURL

Shell
curl --fail-with-body "${PERIPLUS_API_URL:-https://api.periplus.dev}/projects" \
  -H "Authorization: Bearer $PERIPLUS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"id":"0b6c3f3e-0d0e-4a43-9a51-9d4d0a3f6c11","name":"Patent research","description":"Queries for the patent study."}'

curl --fail-with-body -X PATCH "${PERIPLUS_API_URL:-https://api.periplus.dev}/saved-queries/$QUERY_ID" \
  -H "Authorization: Bearer $PERIPLUS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"expected_version":1,"project_id":"0b6c3f3e-0d0e-4a43-9a51-9d4d0a3f6c11","description":"Latest sources."}'

curl --fail-with-body "${PERIPLUS_API_URL:-https://api.periplus.dev}/saved-queries?project_id=0b6c3f3e-0d0e-4a43-9a51-9d4d0a3f6c11" \
  -H "Authorization: Bearer $PERIPLUS_API_KEY"

GET /projects lists the Default Project first, then the rest by name. Send {"project_id": "<project>"} to move a query and {"description": null} to clear a description. Fields you omit stay unchanged.

Open saved queries