Plotly's API

Jump to API response


Beta Endpoints

Endpoints marked as -beta are subject to change, possibly without notice. Behaviour of action may not necessarily remain backwards compatible upon update.


Plotly uses a few terms often which have specific internal meaning.

idlocal: Each user's files are numbered (starting at 0) uniquely. The the idlocal is this unique number for a given user.

fid: This stands for 'file id' and is the combination of a username and a id number (e.g., 'username:10'). Plotly uses this ubiquitously to identify user's files and it is the lookup field in our api urls.

file: The generic term file is used to encompass any file-like object in Plotly. This includes plots, grids, supplemental materials, etc.

reference: File A references file B if file B provides data or context for File A. Plots often reference grids. Plots and grids often reference Extras.

referencer: The reverse relationship of a reference.

metadata: Information belonging to a grid that describes context for the data. For example, component values or machine settings for a given test. The metadata field can only be added to a grid via the grids api and it can only be queried via the search api.


Calls from external libraries use basic authentication using your Plotly username and API key. Your API key can be found on the settings page when you are logged in to the site.

In the future, we will require OAuth

A Plotly-Client-Platform header must be present, consisting of the platform name and an optional version. The version is the version of the client library, not the client language itself. It is a string consisting of only decimal digits and periods, and must be preceded by at least one space.


Plotly-Client-Platform: Lisp
Plotly-Client-Platform: Python 0.2
Plotly-Client-Platform: Python 0.2.5
Plotly-Client-Platform: Python 3 0.3.2

The versions here are: unspecified, 0.2, 0.2.5, and 0.3.2 respectively.

Calls from the webapp have a session cookie, CSRF cookie, and CSRF header as for standard Django applications.


When an API request fails, the response content usually has a 'detail' field. This field gives more information about the failed request. Note that the availability of this field shouldn't be depended on.

400 Bad Request: Simply an improperly formatted request.

401 Unauthorized: The action attempted requires authentication and you are not logged in or did not provide adequate credentials.

403 Forbidden: You are authenticated and the file exists, but you don't have permission to complete the desired action.

404 Not Found: You are authenticated, but either (1) the file doesn't exist or (2) you don't have permission complete the desired action.

405 Method Not Allowed: The endpoint exists but is currently inactive. This usually indicates plans for future support.


View search api page

The search endpoint currently supports searching grid metadata. That is, you cannot perform searches that reach content of of files (e.g., a plot title) or other non-metadata fields (e.g., filename).


View files api page

Performs file-level operations on Plotly accounts.

This included getting the content of Plotly files (e.g., the data in a plot), returning generic meta information about files/folders, trashing files (recoverable), restoring files, permanently deleting files, and (partially) updating writable meta information.


View grids api page

Handles all manipulation of Plotly grids and detail views for meta information about grids.


View plots api page

Handles the retrieving of plot content/meta inforation and the listing of all public or handpicked feed plots.


View extras api page

Handles creating, updating, and getting meta information about related files. Extras are supplemental materials associated with other files, like plots or grids.


View folders api page

An endpoint to create new folders with arbitrarily deep nesting.


View images api page

An endpoint to generate static plot images from plot JSON.


View comments api page

An Endpoint to create and delete comments.


View plot-schema api page

An endpoint to get a schema for validating plotlyjs JSON blobs.


View users api page

An endpoint to list/retrieve user meta information.


View memberships api page


View organizations api page


View subscriptions api page

jupyter notebooks:

View Jupyter notebooks api page


View shapefiles api page

external images:

View External images api page


View dashboards api page


View analysis api page

GET /v2/
Content-Type: application/json
Vary: Accept

    "users": "",
    "plot-schema": "",
    "oauth-apps": "",
    "search": "",
    "files": "",
    "grids": "",
    "plots": "",
    "extras": "",
    "folders": "",
    "images": "",
    "memberships": "",
    "organizations": "",
    "subscriptions": "",
    "comments": "",
    "jupyter-notebooks": "",
    "shapefiles": "",
    "external-images": "",
    "dashboards": "",
    "analysis": ""