---
updatedAt: 2026-06-09T14:53:53.000Z
agentTools:
  projectIndex: https://docs.greynoise.io/llms.txt
---

# Psychic Model Download

Downloads a Psychic model file. The request body selects the model
(`1`, `2`, `3`, `m1`, `m2`, `m3`, `model1`, `model2`, or `model3`).
Models 1, 2, and 3 may set `date` to `latest` or a `YYYY-MM-DD`
date. When `date` is omitted, the latest daily model is used. Models 1,
2, and 3 may also request an inclusive date range with `start_date` and
`end_date`; ranges are limited to 30 days and return one combined
download.
Set `format` to `mmdb` to download a MaxMind DB file. When `format`
is omitted, the binary model format is used.

_License: This endpoint requires the Psychic model meter entitlement
for the requested model. Historical dates also require that model's
Psychic lookback-days entitlement to cover the requested date or range
start date._


# 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"
    }
  },
  "security": [
    {
      "APIKeyHeaderAuth": []
    }
  ],
  "paths": {
    "/v1/psychic": {
      "post": {
        "tags": [
          "Psychic"
        ],
        "summary": "Psychic Model Download",
        "operationId": "postPsychicModelDownload",
        "description": "Downloads a Psychic model file. The request body selects the model\n(`1`, `2`, `3`, `m1`, `m2`, `m3`, `model1`, `model2`, or `model3`).\nModels 1, 2, and 3 may set `date` to `latest` or a `YYYY-MM-DD`\ndate. When `date` is omitted, the latest daily model is used. Models 1,\n2, and 3 may also request an inclusive date range with `start_date` and\n`end_date`; ranges are limited to 30 days and return one combined\ndownload.\nSet `format` to `mmdb` to download a MaxMind DB file. When `format`\nis omitted, the binary model format is used.\n\n_License: This endpoint requires the Psychic model meter entitlement\nfor the requested model. Historical dates also require that model's\nPsychic lookback-days entitlement to cover the requested date or range\nstart date._\n",
        "requestBody": {
          "required": true,
          "description": "Psychic model selector, optional daily model date or range, and optional file format.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PsychicDownloadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK - binary Psychic model file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested filename for saving the response.",
                "schema": {
                  "type": "string",
                  "example": "attachment; filename=\"m2-2026-06-04.bin\""
                }
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/vnd.maxmind.maxmind-db": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/PsychicBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PsychicForbidden"
          },
          "404": {
            "$ref": "#/components/responses/PsychicNotFound"
          },
          "413": {
            "$ref": "#/components/responses/PsychicRequestEntityTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/PsychicTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/PsychicUnexpectedError"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.greynoise.io"
    },
    {
      "url": "http://api.greynoise.io"
    }
  ],
  "components": {
    "securitySchemes": {
      "APIKeyHeaderAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "key"
      }
    },
    "responses": {
      "PsychicBadRequest": {
        "description": "Bad request - request syntax is invalid for the Psychic download endpoint.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PsychicError"
            },
            "examples": {
              "missingModel": {
                "value": {
                  "error": "model is required"
                }
              },
              "invalidDate": {
                "value": {
                  "error": "date must be latest or YYYY-MM-DD"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized. Please check your API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            },
            "example": {
              "message": "Unauthorized"
            }
          }
        }
      },
      "PsychicForbidden": {
        "description": "Forbidden - request is not authorized due to API-key access, Psychic entitlement, or Psychic lookback limitations.\n",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/PsychicError"
                },
                {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              ]
            },
            "examples": {
              "missingEntitlement": {
                "value": {
                  "error": "feature not allowed"
                }
              },
              "lookbackExceeded": {
                "value": {
                  "error": "lookback date exceeds entitlement"
                }
              }
            }
          }
        }
      },
      "PsychicNotFound": {
        "description": "Psychic model file not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PsychicError"
            },
            "example": {
              "error": "not found"
            }
          }
        }
      },
      "PsychicRequestEntityTooLarge": {
        "description": "Request body too large. BI request-body inspection is limited to 32 KiB.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PsychicError"
            },
            "example": {
              "error": "request body too large"
            }
          }
        }
      },
      "PsychicTooManyRequests": {
        "description": "Too many requests - either too many concurrent Psychic range downloads are\nbeing generated, or the requested Psychic model meter has no remaining\nusage. Retry later for concurrent-generation limits, or contact\nsales@greynoise.io to adjust model usage entitlements.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PsychicError"
            },
            "examples": {
              "activeRangeGenerations": {
                "value": {
                  "error": "too many active range generations"
                }
              },
              "usageLimitExceeded": {
                "value": {
                  "error": "usage limit exceeded"
                }
              }
            }
          }
        }
      },
      "PsychicUnexpectedError": {
        "description": "Unexpected Psychic download error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PsychicError"
            },
            "example": {
              "error": "internal error"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorMessage": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      },
      "PsychicError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "PsychicDownloadDate": {
        "type": "string",
        "description": "`latest` or a date in `YYYY-MM-DD` format. Future dates are rejected.",
        "example": "latest"
      },
      "PsychicModel": {
        "type": "string",
        "description": "Psychic model selector. Accepted selectors identify models 1, 2, and 3.",
        "enum": [
          "1",
          "2",
          "3",
          "m1",
          "m2",
          "m3",
          "model1",
          "model2",
          "model3"
        ],
        "example": "model2"
      },
      "PsychicDownloadFormat": {
        "type": "string",
        "description": "Download file format. Defaults to `bin`.",
        "enum": [
          "bin",
          "mmdb"
        ],
        "default": "bin",
        "example": "bin"
      },
      "PsychicDownloadRequest": {
        "type": "object",
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/PsychicModel"
          },
          "date": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PsychicDownloadDate"
              }
            ],
            "description": "When omitted, the latest daily model is used."
          },
          "start_date": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PsychicDownloadDate"
              }
            ],
            "description": "Inclusive range start date. Must be sent with `end_date`, cannot be combined with `date`, and is supported only for models 1, 2, and 3."
          },
          "end_date": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PsychicDownloadDate"
              }
            ],
            "description": "Inclusive range end date. Must be sent with `start_date`, cannot be combined with `date`, and ranges cannot exceed 30 days."
          },
          "format": {
            "$ref": "#/components/schemas/PsychicDownloadFormat"
          }
        }
      }
    }
  }
}
```