> ## Documentation Index > Fetch the complete documentation index at: https://docs.mezmo.com/llms.txt > Use this file to discover all available pages before exploring further. # Creates a new screen > Creates a new screen ## OpenAPI ````yaml /log-analysis.json post /v1/config/screen openapi: 3.0.1 info: title: Log Analysis API description: > *REST API to send log data, export data and manage configuration* To utilize the inline testing functionality here, please go into your Mezmo account and add the following address to your CORS Origins page: `https://docs.mezmo.com`. version: '2.1' servers: - url: https://api.mezmo.com security: - AccessToken: [] - servicekeyAuth: [] - ibmIamAuth: [] tags: - name: Archiving description: > >*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication). The LogDNA Archiving API enables you to programmatically configure your archiving instances via code. Specifically you can set up cold storage buckets to send your logs for long term storage. - name: Board description: > >*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication). The LogDNA's API's Board endpoints are used to create, get, list, and delete boards. - name: Configuration description: > >*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication). The LogDNA API's Configuration endpoints are used to create, update, and delete views, alerts, and categories. - name: Export description: > LogDNA provides two endpoints for exporting your log lines. Read the sections below to learn about each, and determine which is appropriate for your use case. ## Export API v1 The Export API v1 is used to export log lines in [JSONL](https://jsonlines.org/) format. Based on your specific plan, the maximum number of logs returned is limited to 10,000 / 20,000. There are two distinct functionalities: 1. Streaming desired log lines directly from the response as raw text data 2. Specifying an email to receive a link that can be used to the download the desired log lines > Note > When an email address is specified, the desired log lines will not be streamed to the response body. > The response will instead send a notification indicating that the request was successful and that the results > will be sent to the email address provided in the request. This entails archiving and uploading the desired logs > to a storage provider. The email includes a URI to download the logs. Be aware that access to this URI will expire > after 24-48 hours. ## Export API v2 The Export API v2 provides an enhancement over v1, allowing you to export any number of log lines using pagination and by-passing the plan-specific limit imposed in v1. By making (multiple) subsequent requests using the `pagination_id` parameter, you can retrieve logs in batches of JSON until all matching log lines have been returned. Each Export API v2 request is limited to 10,000 lines. ### Pagination Functionality Pagination is only necessary when the desired set of log lines is larger than 10,000, since this is the maximum number of results that can be returned in a given page. If an export does not exceed this size, the behavior is similar to v1 -- all of the logs will be returned in a single "page" and no further requests are needed. When an export does exceed this size, refer to the steps outlined below. This is the expected workflow to export a set (cardinality > 10,000) of log lines that requires pagination: 1. Send an initial request with valid query parameters to retrieve logs. Pass a `null` value for the `pagination_id` in the first request. 2. The JSON response contains 2 fields: `lines` and `pagination_id`. The former is an array containing the corresponding batch (the first batch in this case) of logs and the latter is a token used to retrieve the next page of results. 3. Send a subsequent request using the same initial query parameters and also passing in the token received in the response to the `pagination_id` parameter. This will retrieve the next page of results. 4. Repeat this request-response cycle, updating the `pagination_id` parameter with the token returned in every new response, until the response eventually returns a `null` value for the token. This indicates that the corresponding batch of logs is the last and that you have reached the final page. > Important Considerations > In subsequent requests to paginate through results, make sure none of the query parameters & values are modified from the initial request > (excluding `pagination_id`) > The tokens used in the `pagination_id` parameter are tied to a specific export and page so they can be used repeatedly in requests to return > deterministic results > "0" can be passed in to the `from` and `to` parameters which will be resolved to timestamps for a plan's retention boundary and the current > time respectively. This behavior is independent so the value can be passed interchangeably to the parameters -- resulting in 4 possible scenarios: > - [`from`: \, `to`: \] > - [`from`: 0 (retention boundary), `to`: \] > - [`from`: \, `to`: 0 (current time)] > - [`from`: 0 (retention boundary), `to`: 0 (current time)] - name: Ingestion description: Ingestion API - name: Exclusions description: > >*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication). Control what you store by creating exclusion rules. New lines that match an exclusion rule will not be stored and will not count toward your storage quota. - name: Suspensions description: > >*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication). The LogDNA Start/Stop Ingestion API allows users to programmatically manage their data ingestion status. Users can get the current status of their ingestion, suspend their ingestion, and resume their ingestion. To prevent an accidental API call, the suspension of ingestion requires two subsequent API calls. > You can find instructions on authentication [here](/log-analysis-api/ref#authentication). - name: Usage v1 description: > >*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication). The Usage API provides endpoints for retrieving aggregated usage information for applications, hosts and tags during a time period. While the `to` and `from` times are unix timestamps, the report is granular by day. Therefore only the day portion is used to establish a date range. ### How is **Usage** defined? This API defines usage as a percentage of the total number of lines ingested by the account within the defined period of time. For example, an app called `myapp` that returns a percentage of `15` in the response object has 15 percent of their logs coming from `myapp`. - name: Usage v2 description: > >*Authentication*: You can find instructions on authentication [here](/log-analysis-api/ref#authentication). The Usage API provides endpoints for retrieving aggregated usage information for applications, hosts and tags during a time period. While the `to` and `from` times are unix timestamps, the report is granular by day. Therefore only the day portion is used to establish a date range. ### How is **Usage** defined? This API defines usage as the number of bytes used by the log lines stored on disk by the account within the defined period of time. For example, an app called `myapp` that returns `150,000` total bytes in the response object indicates that `myapp` is consuming `150,000` bytes of disk storage over the time range. paths: /v1/config/screen: post: tags: - Screens summary: Creates a new screen description: Creates a new screen operationId: create-screen requestBody: description: Request body. content: application/json: schema: $ref: '#/components/schemas/screenResource' required: true responses: '200': description: >- A new screen was created successfully! Entire memberResource is returned. content: application/json: schema: $ref: '#/components/schemas/screenResource' '400': description: The supplied request is invalid or malformed. content: application/json: schema: $ref: '#/components/schemas/errResponse' example: error: '"ratio" is required' code: BadRequest status: error components: schemas: screenResource: type: object properties: id: type: string readOnly: true description: The identifier of this screen. account: type: string readOnly: true description: The account this screen belongs to. title: type: string description: The title of this screen. ratio: type: string enum: - '3:2' - '4:3' - '5:4' - '16:9' - '16:10' - '21:9' description: The width to height aspect ratio of this screen. rotate90Degrees: type: boolean description: >- Whether the screen is rotated 90 degrees. Setting to true effectively swaps the width to height ratio. background: type: string enum: - dark - light description: The background color to use when viewing the screen. categories: type: array items: type: string description: A list of string categories the screen belongs to. widgets: type: array items: type: object properties: id: type: string description: The id of this widget. type: type: string enum: - count - gauge - table - time-shifted-graph description: The type for this widget. operation: type: string enum: - count - min - max - avg - cum - diff - percentile-75 - percentile-85 - percentile-95 - percentile-99 description: >- The type of operation to perform on the field indicated in the “field” option. If the "field" option is set to all lines, only "count" can be used and other values may not display any results. duration: type: string oneOf: - enum: - hourly-compare - daily-compare - weekly-compare - iso-weekly-compare - enum: - hourly - daily - weekly - iso-weekly - 1m - 30m - 1h - 2h - 4h - 8h - 12h - 1d - 2d - 4d - 1w - 2w description: >- How far into the past to graph this widget. Time shifted graph widgets must use time shifted durations e.g. "iso-weekly-compare". All other widgets must use regular durations e.g. "hourly". field: type: string description: >- Which field is being operated on and displayed in this widget. Use the special field “__ALL__LINES__” to perform the operation on all lines. match: type: string description: >- A special matching operation done on each value of the field. If the field is a string type then this value is used for equivalence matching. For number types, the supported operators are ["*", ">N", "=N", "<=N"]. If the field is set the special type "__ALL_LINES__", this option is disabled. filter: type: string description: >- An extra query filter to run to match lines. Must be specified as a Mezmo line query e.g. “statusCode:>=400”. label: type: string description: A label that is displayed on the widget. position: type: object properties: start: type: array items: {} description: The top left corner of the widget as an [x, y] coordinate. end: type: array items: {} description: >- The bottom right corner of the widget as an [x, y] coordinate. required: - start - end description: >- The positional coordinates of a widget. Screens coordinates start at at the top left at [1, 1] and increase down and to the right of a screen. additionalProperties: false sort: type: string oneOf: - enum: - asc - desc x-required: true description: >- The order in which the rows of a table are sorted. This option is specific to the "table" widget. rows: type: integer oneOf: - enum: - 3 - 5 - 10 - 15 - 20 - 25 x-required: true description: >- How many rows to include for the table. This option is specific to the "table" widget. leftLabel: type: string oneOf: - {} description: >- Label to display on the left side of a table. This option is specific to the "table" widget. rightLabel: type: string oneOf: - {} description: >- Label to display on the right side of a table. This option is specific to the "table" widget. showBarChart: type: boolean oneOf: - x-required: true description: >- Whether the rows of a table should also be displayed as a bar chart. This option is specific to the "table" widget. groupBy: type: string oneOf: - x-required: true description: >- An additional field with which to group results. This option is specific to the "table" widget. min: type: number format: float oneOf: - x-required: true description: >- The minimum bounds of the gauge. This option is specific to the "gauge" widget. max: type: number format: float oneOf: - x-required: true description: >- The maximum bounds of the gauge. This option is specific to the "gauge" widget. units: type: string oneOf: - {} description: >- A label for the units of this widget. This option is specific to the "count" and "gauge" widgets. format: type: string oneOf: - enum: - number-integer - number-tenths - number-ten-thousandths - number-unformatted - currency-prefix - currency-postfix - bytes-si - percent-integer - percent-thousandths - time-HH:mm:ss x-required: true description: >- How to format the results of this widget. This option is specific to the "count", "gauge", and "table" widgets. required: - id - type - operation - duration - field - position additionalProperties: false required: - id - title - ratio - rotate90Degrees - background additionalProperties: false errResponse: type: object properties: error: type: string description: A human-readable description of the error code: type: string description: A unique code for the type of error status: type: string description: The status of the request securitySchemes: AccessToken: type: apiKey in: header name: Authorization description: > This key is used for all apis with the exception of ingest. You can obtain it following [these instructions](https://docs.mezmo.com/docs/ingestion-key) and placing the key in the header of your call in the format of `Authorization: Token {accesstoken}` For example: ``` curl -H 'Authorization: Token ' ``` servicekeyAuth: type: apiKey in: header name: servicekey description: > (Deprecated) This key is used for v1 and v2 apis with the exception of ingest. Service keys can be used by placing your service key in the `Authorization` header of your api call. *NOTE* Usage of the service key auth mechanism has been deprecated in favor of IAM Access Tokens. Service keys can no longer be created, but can still be used for v1 and v2 apis while the transition takes place ````