Introspection

Datasette includes some pages and JSON API endpoints for introspecting the current instance. These can be used to understand some of the internals of Datasette and to see how a particular instance has been configured.

Each of these pages can be viewed in your browser. Add .json to the URL to get back the contents as JSON.

/-/metadata

Shows the contents of the metadata.json file that was passed to datasette serve, if any. Metadata example:

{
    "license": "CC Attribution 4.0 License",
    "license_url": "http://creativecommons.org/licenses/by/4.0/",
    "source": "fivethirtyeight/data on GitHub",
    "source_url": "https://github.com/fivethirtyeight/data",
    "title": "Five Thirty Eight",
    "databases": {

    }
}

/-/versions

Shows the version of Datasette, Python and SQLite. Versions example:

{
    "datasette": {
        "version": "0.60"
    },
    "python": {
        "full": "3.8.12 (default, Dec 21 2021, 10:45:09) \n[GCC 10.2.1 20210110]",
        "version": "3.8.12"
    },
    "sqlite": {
        "extensions": {
            "json1": null
        },
        "fts_versions": [
            "FTS5",
            "FTS4",
            "FTS3"
        ],
        "compile_options": [
            "COMPILER=gcc-6.3.0 20170516",
            "ENABLE_FTS3",
            "ENABLE_FTS4",
            "ENABLE_FTS5",
            "ENABLE_JSON1",
            "ENABLE_RTREE",
            "THREADSAFE=1"
        ],
        "version": "3.37.0"
    }
}

/-/plugins

Shows a list of currently installed plugins and their versions. Plugins example:

[
    {
        "name": "datasette_cluster_map",
        "static": true,
        "templates": false,
        "version": "0.10",
        "hooks": ["extra_css_urls", "extra_js_urls", "extra_body_script"]
    }
]

Add ?all=1 to include details of the default plugins baked into Datasette.

/-/settings

Shows the Settings for this instance of Datasette. Settings example:

{
    "default_facet_size": 30,
    "default_page_size": 100,
    "facet_suggest_time_limit_ms": 50,
    "facet_time_limit_ms": 1000,
    "max_returned_rows": 1000,
    "sql_time_limit_ms": 1000
}

/-/config

Shows the configuration for this instance of Datasette. This is generally the contents of the datasette.yaml or datasette.json file, which can include plugin configuration as well. Config example:

{
    "settings": {
        "template_debug": true,
        "trace_debug": true,
        "force_https_urls": true
    }
}

Any keys that include the one of the following substrings in their names will be returned as redacted *** output, to help avoid accidentally leaking private configuration information: secret, key, password, token, hash, dsn.

/-/databases

Shows currently attached databases. Databases example:

[
    {
        "hash": null,
        "is_memory": false,
        "is_mutable": true,
        "name": "fixtures",
        "path": "fixtures.db",
        "size": 225280
    }
]

/-/jump

Returns a JSON list of items that the current actor has permission to view for Datasette's jump menu. By default this includes visible databases, tables, views and canned queries, and plugins can contribute additional items.

The endpoint supports a ?q= query parameter for filtering items by name. Canned queries with a configured title also include a display_name in their results, and can be found by searching for that title. Plugins can provide the same extra field from jump_items_sql by returning a display_name column and setting JumpSQL(..., has_display_name=True).

Jump example:

{
    "matches": [
        {
            "name": "fixtures",
            "url": "/fixtures",
            "type": "database",
            "description": "Database"
        },
        {
            "name": "fixtures: facetable",
            "url": "/fixtures/facetable",
            "type": "table",
            "description": "Table"
        },
        {
            "name": "fixtures: recent_releases",
            "display_name": "Recent Datasette releases",
            "url": "/fixtures/recent_releases",
            "type": "query",
            "description": "Canned query"
        }
    ],
    "truncated": false
}

Search example with ?q=facet returns only items matching .*facet.*:

{
    "matches": [
        {
            "name": "fixtures: facetable",
            "url": "/fixtures/facetable",
            "type": "table",
            "description": "Table"
        }
    ],
    "truncated": false
}

When multiple search terms are provided (e.g., ?q=user+profile), items must match the pattern .*user.*profile.*. Results are ordered by relevance, then by item type and shortest display name.

/-/threads

Shows details of threads and asyncio tasks. Threads example:

{
    "num_threads": 2,
    "threads": [
        {
            "daemon": false,
            "ident": 4759197120,
            "name": "MainThread"
        },
        {
            "daemon": true,
            "ident": 123145319682048,
            "name": "Thread-1"
        },
    ],
    "num_tasks": 3,
    "tasks": [
        "<Task pending coro=<RequestResponseCycle.run_asgi() running at uvicorn/protocols/http/httptools_impl.py:385> cb=[set.discard()]>",
        "<Task pending coro=<Server.serve() running at uvicorn/main.py:361> wait_for=<Future pending cb=[<TaskWakeupMethWrapper object at 0x10365c3d0>()]> cb=[run_until_complete.<locals>.<lambda>()]>",
        "<Task pending coro=<LifespanOn.main() running at uvicorn/lifespan/on.py:48> wait_for=<Future pending cb=[<TaskWakeupMethWrapper object at 0x10364f050>()]>>"
    ]
}

/-/actor

Shows the currently authenticated actor. Useful for debugging Datasette authentication plugins.

{
    "actor": {
        "id": 1,
        "username": "some-user"
    }
}

/-/messages

The debug tool at /-/messages can be used to set flash messages to try out that feature. See .add_message(request, message, type=datasette.INFO) for details of this feature.