# mon-get-stats
## Description
Gets time-series data for the specified statistics.
**Note**
When you create a new metric using the `mon-put-data` command, it can take up to two minutes before you can retrieve statistics on the new metric using the `mon-get-stats` command. However, it can take up to fifteen minutes before the new metric appears in the list of metrics retrieved using the `mon-list-metrics` command.
## Syntax
****mon-get-stats** MetricName --namespace *value* --statistics *value*[,*value*...] [--dimensions "key1=*value1*,key2=*value2*..." ] [--end-time *value*] [--period *value*] [--start-time *value*] [--unit *value*] [Common Options] **
## Options
| Name | Description |
| --- | --- |
| `MetricName` | The name of the metric. You can also set this value using `--metric-name`. Type: Argument Valid values: Any valid metric name between 1 and 255 characters. Default: n/a Required: Yes |
| `--dimensions` `"key1=value1,key2=value2..." ` | The dimensions of the metric. You can specify dimensions two ways and the formats can be combined or used interchangeably: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/cli/cli-mon-get-stats.html) Type: Map Valid values: A string of the format name=value, where the key is the name of the dimension, and the value is the dimension's value. The dimension names, and values must be an ANSI string between 1 and 250 characters long. A maximum of 10 dimensions are allowed. Default: n/a Required: No |
| `--end-time` `VALUE` | The latest allowed timestamp for returned data points. The ending time is exclusive. Timestamps are specified using ISO8601 combined format. For example the date and time July 30th, 2013 at 12:30:00 PST would be represented as 2013-07-30T12:30:00-07:00, or in UTC: 2013-07-30T19:30:00Z. The highest resolution that can be returned by CloudWatch is 1 minute, as such all timestamps are rounded down to the nearest minute. Type: Argument Valid values: A valid timestamp represented in ISO8601 format with time zone offset, or UTC indicator. Default: The current date/time. Required: No |
| `-n, --namespace` `VALUE` | The namespace of the metric. For more information about namespaces, see [AWS Namespaces](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/aws-namespaces.html). Type: String Valid values: A valid namespace between 1 and 250 characters in length. Default: n/a Required: Yes |
| `--period` `VALUE` | The granularity, in seconds, to retrieve statistics for. The period must be at least 60 seconds and must be a multiple of 60. Type: Argument Valid values: A number, in seconds that is a multiple of 60 seconds. Default: 60 seconds. Required: No |
| `-s, --statistics` `VALUE1,VALUE2,VALUE3...` | The statistics to be returned for the specified metric. Type: Enumeration Valid values: Average, Sum, Maximum, or Minimum Default: n/a Required: Yes |
| `--start-time` `VALUE` | The first allowed timestamp for returned data points. The starting time is inclusive. Timestamps are specified using ISO8601 combined format. For example the date and time July 30th, 2013 at 12:30:00 PST would be represented as 2013-07-30T12:30:00-07:00, or in UTC: 2013-07-30T19:30:00Z. The highest resolution that can be returned by CloudWatch is 1 minute, as such all timestamps are rounded down to the nearest minute. Type: Argument Valid values: A valid timestamp represented in ISO8601 format with time zone offset, or UTC indicator. Default: One hour before the current time. Required: No |
| `--unit` `VALUE` | The unit to retrieve the metrics for. Metrics may be reported in multiple units, this retrieve a specific unit for a given metric. Not requesting a unit will result in all units being returned. If the metric is only ever reported with one unit this will have no effect. Type: Enumeration Valid values: One of the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/cli/cli-mon-get-stats.html) Default: n/a Required: No |
## Common options
| Name | Description |
| --- | --- |
| `--aws-credential-file` `VALUE` | The location of the file with your AWS credentials. You can set this value using the environment variable `AWS_CREDENTIAL_FILE`. If you define the environment variable or you provide the path to the credential file, the file must exist or the request fails. All CloudWatch requests must be signed using your access key ID and secret access key. Type: String Valid values: A valid path to a file containing your access key ID and secret access key. Default: Uses the environment variable `AWS_CREDENTIAL_FILE`, if set. |
| `-C, --ec2-cert-file-path` `VALUE` | The location of your EC2 certificate file for signing requests. You can use the environment variable `EC2_CERT` to specify this value. Type: String Valid values: A valid file path to the PEM file provided by Amazon EC2 or AWS Identity and Access Management. Default: Uses the environment variable `EC2_CERT`, if set. |
| `--connection-timeout` `VALUE` | The connection timeout value, in seconds. Type: Integer Valid values: Any positive number. Default: 30 |
| `--delimiter` `VALUE` | The delimiter to use when displaying delimited (long) results. Type: String Valid values: Any string. Default: Comma (,) |
| `--headers` `` | If you are displaying tabular or delimited results, include the column headers. If you are showing XML results, return the HTTP headers from the service request, if applicable. Type: Flag Valid values: When present, shows headers. Default: The `--headers` option is off by default. |
| `-I, --access-key-id` `VALUE` | The access key ID that will be used, in conjunction with the secret key, to sign the request. This must be used in conjunction with --secret-key, otherwise the option is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected. Type: String Valid values: A valid access key ID. Default: None |
| `-K, --ec2-private-key-file-path` `VALUE` | The private key that will be used to sign the request. Using public/private keys causes the CLI to use SOAP. The request is signed with a public certificate and private key. This parameter must be used in conjunction with `EC2_CERT`, otherwise the value is ignored. The value of the environment variable `EC2_PRIVATE_KEY` will be used if it is set, and this option is not specified. This option is ignored if the environment variable `AWS_CREDENTIAL_FILE` is set, or `--aws-credentials-file` is used. All requests to CloudWatch must be signed, otherwise the request is rejected. Type: String Valid values: The path to a valid ASN.1 private key. Default: None |
| `--region` `VALUE` | The region requests are directed to. You can use the environment variable `EC2_REGION` to specify the value. The region is used to create the URL used to call CloudWatch, and must be a valid Amazon Web Services (AWS) region. Type: String Valid values: Any AWS region, for example, us-east-1. Default: us-east-1, unless the `EC2_REGION` environment variable is set. |
| `S, --secret-key` `VALUE` | The secret access key that will be used to sign the request, in conjunction with an access key ID. This parameter must be used in conjunction with `--access-key-id`, otherwise this option is ignored. Type: String Valid values: Your access key ID. Default: None |
| `--show-empty-fields` `` | Shows empty fields using (nil) as a placeholder to indicate that this data was not requested. Type: Flag Valid values: None Default: Empty fields are not shown by default. |
| `--show-request` `` | Displays the URL the CLI uses to call AWS. Type: Flag Valid values: None Default: false |
| `--show-table, --show-long, --show-xml, --quiet` `` | Specifies how the results are displayed: in a table, delimited (long), XML, or no output (quiet). The `--show-table` display shows a subset of the data in fixed column-width form; `--show-long` shows all of the returned values delimited by a character; `--show-xml` is the raw return from the service; and `--quiet` suppresses all standard output. All options are mutually exclusive, with the priority `--show-table`, `--show-long`, `--show-xml`, and `--quiet`. Type: Flag Valid values: None Default: `--show-table` |
| `-U, --url` `VALUE` | The URL used to contact CloudWatch. You can set this value using the environment variable `AWS_CLOUDWATCH_URL`. This value is used in conjunction with `--region` to create the expected URL. This option overrides the URL for the service call. Type: String Valid values: A valid HTTP or HTTPS URL. Default: Uses the value specified in `AWS_CLOUDWATCH_URL`, if set. |
## Output
This command returns a table that contains the following:
+ Time - The time the metrics were taken.
+ SampleCount - No description available for this column.
+ Average - The average value.
+ Sum - The sum of values.
+ Minimum - The minimum observed value.
+ Maximum - The maximum observed value.
+ Unit - The unit of the metric.
The Amazon CloudWatch CLI displays errors on stderr.
## Examples
### Example request
This example returns the average, minimum, and maximum CPU utilization for EC2 instance i-c07704a9, at 1 hour resolution.
```
mon-get-stats CPUUtilization --start-time 2013-02-14T23:00:00.000Z --end-time 2013-03-14T23:00:00.000Z --period 3600 --statistics "Average,Minimum,Maximum" --namespace "AWS/EC2" --dimensions "InstanceId=i-c07704a9"
```
This is an example of an output of the Samples and Average metrics at one minute resolution.
```
Time Samples Average Unit
2013-05-19 00:03:00 2.0 0.19 Percent
2013-05-19 00:04:00 2.0 0 Percent
2013-05-19 00:05:00 2.0 0 Percent
2013-05-19 00:06:00 2.0 0 Percent
2013-05-19 00:07:00 2.0 0 Percent
2013-05-19 00:08:00 2.0 0 Percent
2013-05-19 00:09:00 2.0 0 Percent
2013-05-19 00:10:00 2.0 0 Percent
2013-05-19 00:11:00 2.0 0 Percent
2013-05-19 00:12:00 2.0 0.195 Percent
2013-05-19 00:13:00 2.0 0.215 Percent
...
```
### Example request
This example returns CPU utilization across your EC2 fleet.
```
mon-get-stats CPUUtilization --start-time 2013-02-14T23:00:00.000Z --end-time 2013-03-14T23:00:00.000Z --period 3600 --statistics "Average,Minimum,Maximum" --namespace "AWS/EC2"
```
### Example request
This example returns the average, minimum, and maximum request count made to the test stack of MyService for a particular user, at 1 hour resolution.
```
mon-get-stats RequestCount --start-time 2013-11-24T23:00:00.000Z --end-time 2013-11-25T23:00:00.000Z --period 3600 --statistics "Average,Minimum,Maximum" --namespace "MyService" --dimensions "User=SomeUser,Stack=Test"
```
### Example request
This example shows RequestCount statistics across all of "MyService".
```
mon-get-stats RequestCount --start-time 2013-11-24T23:00:00.000Z --end-time 2013-11-25T23:00:00.000Z --period 3600 --statistics "Average,Minimum,Maximum,SampleCount" --namespace "MyService"
```
## Related topics
### Download
+ [Set up the command line interface](SetupCLI.md)
### Related action
+ [GetMetricStatistics](http://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricStatistics.html)
### Related commands
+ [mon-list-metrics](cli-mon-list-metrics.md)
+ [mon-describe-alarms](cli-mon-describe-alarms.md)