---
updatedAt: 2026-04-29T22:56:06.000Z
agentTools:
  projectIndex: https://docs.greynoise.io/llms.txt
---

# Get Sessions

Returns a paginated list of network sessions matching the query criteria.
Sessions represent individual network connections captured by GreyNoise sensors.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "description": "GreyNoise is a cybersecurity company that collects and analyzes Internet-wide scan and attack traffic. Use GreyNoise to contextualize existing alerts, filter false-positives, identify compromised devices, and track emerging threats.",
    "version": "3.0.0",
    "title": "GreyNoise API",
    "contact": {
      "email": "hello@greynoise.io"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.greynoise.io/terms"
    }
  },
  "tags": [
    {
      "name": "Sessions",
      "description": "Endpoints for querying, analyzing, and exporting raw network session (PCAP)\ndata captured by GreyNoise sensors. Use the `scope` parameter to control\ndata access (workspace or demo). Required entitlements vary by scope.\n"
    }
  ],
  "security": [
    {
      "APIKeyHeaderAuth": []
    }
  ],
  "paths": {
    "/v3/sessions": {
      "get": {
        "tags": [
          "Sessions"
        ],
        "summary": "Get Sessions",
        "operationId": "getSessions",
        "description": "Returns a paginated list of network sessions matching the query criteria.\nSessions represent individual network connections captured by GreyNoise sensors.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/scope"
          },
          {
            "in": "query",
            "name": "start_time",
            "description": "Start time for the query range (ISO 8601 format).",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2025-01-01T00:00:00Z"
          },
          {
            "in": "query",
            "name": "end_time",
            "description": "End time for the query range (ISO 8601 format).",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2025-01-07T23:59:59Z"
          },
          {
            "in": "query",
            "name": "query",
            "description": "Lucene query string to filter sessions.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "page",
            "description": "Page number for pagination.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "in": "query",
            "name": "page_size",
            "description": "Number of results per page.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 25,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "in": "query",
            "name": "sort_by",
            "description": "Field to sort results by.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "lastPacket"
            }
          },
          {
            "in": "query",
            "name": "sort_desc",
            "description": "Whether to sort in descending order.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK - request successful.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/ExceededLimit"
          },
          "500": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.greynoise.io"
    },
    {
      "url": "http://api.greynoise.io"
    }
  ],
  "components": {
    "securitySchemes": {
      "APIKeyHeaderAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "key"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request - request syntax is invalid for the specified endpoint.\nVerify request syntax and try again.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            },
            "example": {
              "message": "Invalid parameter"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized. Please check your API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            },
            "example": {
              "message": "Unauthorized"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden - request is not authorized due to an invalid API key or plan limitations.\nIf due to plan limitations, contact sales@greynoise.io to upgrade your plan and unlock full results.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            },
            "example": {
              "message": "Forbidden"
            }
          }
        }
      },
      "UnexpectedError": {
        "description": "Unexpected error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            },
            "example": {
              "message": "Encountered error while performing request"
            }
          }
        }
      },
      "ExceededLimit": {
        "description": "Too many requests. You've hit the rate-limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            },
            "example": {
              "message": "You've hit the rate limit for this endpoint."
            }
          }
        }
      }
    },
    "parameters": {
      "scope": {
        "name": "scope",
        "in": "query",
        "description": "Controls the data scope for the query.\n- `workspace`: Query data from the current workspace (default). Requires the Sensors entitlement.\n- `demo`: Query demo/sample data. Requires the Swarm entitlement. Not available on export endpoints.\n",
        "required": false,
        "schema": {
          "type": "string",
          "default": "workspace",
          "enum": [
            "workspace",
            "demo"
          ]
        }
      }
    },
    "schemas": {
      "ErrorMessage": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      },
      "Session": {
        "type": "object",
        "description": "A network session captured by GreyNoise sensors. Sessions contain network\nflow data, protocol details, and enrichment metadata. The full set of fields\nis dynamic and can be discovered via the `/v3/sessions/fields` endpoint.\n",
        "additionalProperties": true,
        "properties": {
          "_id": {
            "type": "string",
            "description": "Unique session identifier.",
            "example": "2505-abcdef123456"
          },
          "firstPacket": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the first packet in the session.",
            "example": "2025-01-15T10:30:00Z"
          },
          "lastPacket": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the last packet in the session.",
            "example": "2025-01-15T10:30:05Z"
          },
          "source.ip": {
            "type": "string",
            "description": "Source IP address.",
            "example": "203.0.113.45"
          },
          "source.port": {
            "type": "integer",
            "description": "Source port number.",
            "example": 54321
          },
          "destination.ip": {
            "type": "string",
            "description": "Destination IP address.",
            "example": "198.51.100.10"
          },
          "destination.port": {
            "type": "integer",
            "description": "Destination port number.",
            "example": 443
          },
          "source.bytes": {
            "type": "integer",
            "description": "Total bytes sent from source.",
            "example": 1024
          },
          "source.packets": {
            "type": "integer",
            "description": "Total packets sent from source.",
            "example": 10
          },
          "destination.bytes": {
            "type": "integer",
            "description": "Total bytes sent from destination.",
            "example": 2048
          },
          "destination.packets": {
            "type": "integer",
            "description": "Total packets sent from destination.",
            "example": 8
          },
          "classification": {
            "type": "string",
            "description": "GreyNoise classification of the source IP.",
            "example": "malicious"
          }
        }
      },
      "SessionsResponse": {
        "type": "object",
        "properties": {
          "sessions": {
            "type": "array",
            "description": "Array of session objects matching the query.",
            "items": {
              "$ref": "#/components/schemas/Session"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of sessions matching the query.",
            "example": 150
          },
          "pagination": {
            "$ref": "#/components/schemas/SessionPagination"
          },
          "request_metadata": {
            "$ref": "#/components/schemas/SessionRequestMetadata"
          }
        }
      },
      "SessionPagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "description": "Current page number.",
            "example": 1
          },
          "page_size": {
            "type": "integer",
            "description": "Number of results per page.",
            "example": 25
          },
          "sort_by": {
            "type": "string",
            "description": "Field used for sorting.",
            "example": "lastPacket"
          },
          "sort_desc": {
            "type": "boolean",
            "description": "Whether results are sorted in descending order.",
            "example": true
          }
        }
      },
      "SessionRequestMetadata": {
        "type": "object",
        "properties": {
          "start_time": {
            "type": "string",
            "description": "Start time of the query range.",
            "example": "2025-01-01T00:00:00Z"
          },
          "end_time": {
            "type": "string",
            "description": "End time of the query range.",
            "example": "2025-01-07T23:59:59Z"
          },
          "query": {
            "type": "string",
            "description": "The Lucene query string used."
          }
        }
      }
    }
  }
}
```