---
title: Timeboard API
description: >-
  DEPRECATED - API for the deprecated Timeboard endpoint. Use the Dashboard
  endpoint for dashboard operations instead.
breadcrumbs: Docs > Dashboards > Graphing Guides > Timeboard API
---

# Timeboard API

{% alert level="warning" %}
This endpoint is outdated. Use the [new Dashboard endpoint](https://docs.datadoghq.com/api/v1/dashboards/) instead.
{% /alert %}

The `Timeboard` endpoint allows you to programmatically create, update delete and query timeboards.

## Create a timeboard{% #create-a-timeboard %}

### Signature{% #signature %}

`POST https://api.datadoghq.com/api/v1/dash`

### Arguments{% #arguments %}

- **`title`** [*required*]: The name of the dashboard.

- **`description`** [*required*]: A description of the dashboard's content.

- **`graphs`** [*optional*, *default*=**None**]: A list of graph definitions. Graph definitions follow this form:

  - **`title`** [*required*]: The name of the graph.
  - **`definition`** [*optional*, *default*=**None**]:
    - `events` [*optional*, *default*=**None**]: The query for event overlay.
    - `requests` [*optional*, *default*=**None**]: The metric query, line type, style, conditional formats, and aggregator.
    - `viz` [*optional*, *default*=**timeseries**]: The type of visualization.

- **`template_variables`** [*optional*, *default*=**None**]: A list of template variables for using Dashboard templating. Template variable definitions follow this form:

  - **`name`** [*required*]: The name of the variable.
  - **`prefix`** [*optional*, *default*=**None**]: The tag prefix associated with the variable. Only tags with this prefix appear in the variable dropdown.
  - **`default`** [*optional*, *default*=**None**]: The default value for the template variable on dashboard load.

### Examples{% #examples %}

{% tab title="Python" %}

```python
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

title = "My Timeboard"
description = "An informative timeboard."
graphs = [{
    "definition": {
        "events": [],
        "requests": [
            {"q": "avg:system.mem.free{*}"}
        ],
        "viz": "timeseries"
    },
    "title": "Average Memory Free"
}]

template_variables = [{
    "name": "host1",
    "prefix": "host",
    "default": "host:my-host"
}]

read_only = True
api.Timeboard.create(title=title,
                     description=description,
                     graphs=graphs,
                     template_variables=template_variables,
                     read_only=read_only)
```

{% /tab %}

{% tab title="Ruby" %}

```ruby
require 'rubygems'
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

# Create a timeboard.
title = 'My First Metrics'
description = 'And they are marvelous.'
graphs = [{
    "definition" => {
        "events" => [],
        "requests" => [{
            "q" => "avg:system.mem.free{*}"
        }],
        "viz" => "timeseries"
    },
    "title" => "Average Memory Free"
}]
template_variables = [{
    "name" => "host1",
    "prefix" => "host",
    "default" => "host:my-host"
}]

dog.create_dashboard(title, description, graphs, template_variables)
```

{% /tab %}

{% tab title="Bash" %}

```bash
api_key=<DATADOG_API_KEY>
app_key=<DATADOG_APPLICATION_KEY>

curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ],
              "viz": "timeseries"
          }
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }],
      "read_only": "True"
}' \
"https://api.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}"
```

{% /tab %}

## Update a timeboard{% #update-a-timeboard %}

### Signature{% #signature-1 %}

`PUT https://api.datadoghq.com/api/v1/dash/<TIMEBOARD_ID>`

### Arguments{% #arguments-1 %}

- **`title`** [*required*]: The name of the dashboard.

- **`description`** [*required*]: A description of the dashboard's contents.

- **`graphs`** [*required*]: A list of graph definitions. Graph definitions follow this form:

  - **`title`** [*required*]: The name of the graph.
  - **`definition`** [*required*]: The graph definition. Example: `{"requests": [{"q": "system.cpu.idle{*} by {host}"}`

- **`template_variables`** [*optional*, *default*=**None**]: A list of template variables for using Dashboard templating. Template variable definitions follow this form:

  - **`name`** [*required*]: The name of the variable.

  - **`prefix`** [*optional*, *default*=**None**]: The tag prefix associated with the variable. Only tags with this prefix appear in the variable dropdown.

  - **`default`** [*optional*, *default*=**None**]: The default value for the template variable on dashboard load.

### Examples{% #examples-1 %}

{% tab title="Python" %}

```python
from datadog import initialize, api

options = {'api_key': '<DATADOG_API_KEY>',
           'app_key': '<DATADOG_APPLICATION_KEY>'}

initialize(**options)

title = 'My Timeboard'
description = 'A new and improved timeboard!'
graphs = [{'definition': {'events': [],
                          'requests': [{
                            'q': 'avg:system.mem.free{*} by {host}'}],
                          'viz': 'timeseries'},
          'title': 'Average Memory Free By Host'}]
template_variables = [{'name': 'host1', 'prefix': 'host',
                       'default': 'host:my-host'}]
read_only = True

api.Timeboard.update(
    4952,
    title=title,
    description=description,
    graphs=graphs,
    template_variables=template_variables,
    read_only=read_only,
)
```

{% /tab %}

{% tab title="Ruby" %}

```ruby
require 'rubygems'
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

dash_id = '2551'
title = 'New and Improved Timeboard'
description = 'This has all the new hotness.'
graphs = [{
    "definition" => {
        "events" => [],
        "requests" => [{
            "q" => "avg:system.mem.free{*}"
        }],
        "viz" => "timeseries"
    },
    "title" => "Average Memory Free"
}]
template_variables = [{
    "name" => "host1",
    "prefix" => "host",
    "default" => "host:my-host"
}]

dog.update_dashboard(dash_id, title, description, graphs, template_variables)
```

{% /tab %}

{% tab title="Bash" %}

```bash
api_key=<DATADOG_API_KEY>
app_key=<DATADOG_APPLICATION_KEY>
dash_id=2532

# Create a dashboard to get. Use jq (http://stedolan.github.io/jq/download/) to get the dash id.
dash_id=$(curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ],
              "viz": "timeseries"
          }
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
  }' \
"https://api.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}" | jq '.dash.id')

curl  -X PUT -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Sum of Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "sum:system.mem.free{*}"}
              ],
              "viz": "timeseries"
          }
      }],
      "title" : "Sum Memory Free Shell",
      "description" : "An updated dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
}' \
"https://api.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
```

{% /tab %}

## Delete a timeboard{% #delete-a-timeboard %}

Delete an existing timeboard. *This end point takes no JSON arguments.*

### Signature{% #signature-2 %}

`DELETE https://api.datadoghq.com/api/v1/dash/<TIMEBOARD_ID>`

### Arguments{% #arguments-2 %}

*This end point takes no JSON arguments.*

### Examples{% #examples-2 %}

{% tab title="Python" %}

```python
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

title = "My Timeboard"
description = "An informative timeboard."
graphs = [{
    "definition": {
        "events": [],
        "requests": [
            {"q": "avg:system.mem.free{*}"}
        ],
        "viz": "timeseries"
    },
    "title": "Average Memory Free"
}]

template_variables = [{
    "name": "host1",
    "prefix": "host",
    "default": "host:my-host"
}]

newboard = api.Timeboard.create(title=title,
                                description=description,
                                graphs=graphs,
                                template_variables=template_variables)

api.Timeboard.delete(newboard['dash']['id'])
```

{% /tab %}

{% tab title="Ruby" %}

```ruby
require 'rubygems'
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

dash_id = '2534'
dog.delete_dashboard(dash_id)
```

{% /tab %}

{% tab title="Bash" %}

```bash
api_key=<DATADOG_API_KEY>
app_key=<DATADOG_APPLICATION_KEY>
dash_id=2471

# Create a dashboard to delete. Use jq (http://stedolan.github.io/jq/download/) to get the dash id.
dash_id=$(curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ],
              "viz": "timeseries"
          }
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
  }' \
"https://api.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}" | jq '.dash.id')

curl -X DELETE "https://api.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
```

{% /tab %}

## Get a timeboard{% #get-a-timeboard %}

Fetch an existing dashboard's definition.

### Signature{% #signature-3 %}

`GET https://api.datadoghq.com/api/v1/dash/<TIMEBOARD_ID>`

### Arguments{% #arguments-3 %}

*This end point takes no JSON arguments.*

### Examples{% #examples-3 %}

{% tab title="Python" %}

```python
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

api.Timeboard.get(4953)
```

{% /tab %}

{% tab title="Ruby" %}

```ruby
require 'rubygems'
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

dash_id = '2542'
dog.get_dashboard(dash_id)
```

{% /tab %}

{% tab title="Bash" %}

```bash
api_key=<DATADOG_API_KEY>
app_key=<DATADOG_APPLICATION_KEY>
dash_id=2473

# Create a dashboard to get. Use jq (http://stedolan.github.io/jq/download/) to get the dash id.
dash_id=$(curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ],
              "viz": "timeseries"
          }
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
  }' \
"https://api.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}" | jq '.dash.id')

curl "https://api.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
```

{% /tab %}

## Get all timeboards{% #get-all-timeboards %}

Fetch all of your timeboard definitions.

### Signature{% #signature-4 %}

`GET https://api.datadoghq.com/api/v1/dash`

### Arguments{% #arguments-4 %}

*This end point takes no JSON arguments.*

### Examples{% #examples-4 %}

{% tab title="Python" %}

```python
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

print api.Timeboard.get_all()
```

{% /tab %}

{% tab title="Ruby" %}

```ruby
require 'rubygems'
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

dog.get_dashboards
```

{% /tab %}

{% tab title="Bash" %}

```bash
api_key=<DATADOG_API_KEY>
app_key=<DATADOG_APPLICATION_KEY>

curl "https://api.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}"
```

{% /tab %}