---
updatedAt: 2026-07-13T22:45:20.000Z
agentTools:
  projectIndex: https://docs.greynoise.io/llms.txt
---

# List Articles

Returns a paginated list of published articles (Threat Briefs). Supports
filtering by category, search term, and pagination parameters.


# 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": "Threat Briefs",
      "description": "Endpoints for browsing GreyNoise research articles (Threat Briefs) and\nsubscribing to them as RSS feeds. Browsing requires workspace-level\nauthentication and appropriate entitlements; the community RSS feed is public.\n"
    }
  ],
  "security": [
    {
      "APIKeyHeaderAuth": []
    }
  ],
  "paths": {
    "/v3/articles": {
      "get": {
        "tags": [
          "Threat Briefs"
        ],
        "summary": "List Articles",
        "operationId": "listArticles",
        "description": "Returns a paginated list of published articles (Threat Briefs). Supports\nfiltering by category, search term, and pagination parameters.\n",
        "parameters": [
          {
            "in": "query",
            "name": "page",
            "description": "Page number for pagination (1-indexed).",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "in": "query",
            "name": "size",
            "description": "Number of articles per page.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "search",
            "description": "Case-insensitive search across title, subtitle, and description.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "category",
            "description": "Filter articles by category value.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_by",
            "description": "Field to sort results by.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "published_at"
            }
          },
          {
            "in": "query",
            "name": "sort_desc",
            "description": "Sort in descending order. Set to `false` for ascending.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of published articles.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListArticlesResponse"
                }
              }
            }
          },
          "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."
            }
          }
        }
      }
    },
    "schemas": {
      "Article": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique article identifier.",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "title": {
            "type": "string",
            "description": "Article title.",
            "example": "Understanding Internet Background Noise"
          },
          "subtitle": {
            "type": "string",
            "description": "Article subtitle.",
            "example": "A deep dive into scan traffic"
          },
          "description": {
            "type": "string",
            "description": "Article description or body text."
          },
          "category": {
            "$ref": "#/components/schemas/ArticleCategory"
          },
          "author": {
            "type": "string",
            "description": "Name of the article author.",
            "example": "GreyNoise Research"
          },
          "s3_url": {
            "type": "string",
            "description": "Presigned URL to the article PDF. Empty for a linked article, which carries an\nexternal `link` instead. Exactly one of `s3_url` and `link` is populated.\n"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "description": "External URL for a linked article, such as a blog post. Empty for a PDF brief.\nExactly one of `s3_url` and `link` is populated.\n",
            "example": "https://www.greynoise.io/blog/example-post"
          },
          "thumbnail_url": {
            "type": "string",
            "description": "URL to the article thumbnail image."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the article was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the article was last updated."
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the article was published. Omitted if unpublished."
          },
          "is_published": {
            "type": "boolean",
            "description": "Whether the article is currently published."
          }
        }
      },
      "ArticleCategory": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique category identifier."
          },
          "label": {
            "type": "string",
            "description": "Display label for the category.",
            "example": "Threat Intelligence"
          },
          "value": {
            "type": "string",
            "description": "Machine-readable category value.",
            "example": "threat-intelligence"
          },
          "color": {
            "type": "string",
            "description": "Hex color code for the category.",
            "example": "#FF5733"
          }
        }
      },
      "ListArticlesResponse": {
        "type": "object",
        "properties": {
          "metadata": {
            "$ref": "#/components/schemas/ArticleListMetadata"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Article"
            }
          }
        }
      },
      "ArticleListMetadata": {
        "type": "object",
        "properties": {
          "total_results": {
            "type": "integer",
            "description": "Total number of articles matching the query.",
            "example": 42
          },
          "current_page": {
            "type": "integer",
            "description": "Current page number.",
            "example": 1
          },
          "count": {
            "type": "integer",
            "description": "Number of articles returned in this page.",
            "example": 10
          }
        }
      },
      "ErrorMessage": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      }
    }
  }
}
```