---
title: "Search by author"
method: POST
path: "/api/authors"
tags: ["Authors"]
---

# Search by author

`POST /api/authors`

## Request

- Base URL: `https://v3-api.newscatcherapi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://v3-api.newscatcherapi.com/api/authors`
- Auth: none declared. Required headers: `x-api-token`

Search for articles written by a given author, matched as a phrase against the article's author byline. Supports filtering by language, country, source, publication date, and dozens of other parameters; does not support full-text query (q) or clustering.

## Headers

- `x-api-token` string, required: Your NewsCatcher API key, used to authenticate this request.

## Request body

- AuthorSearchRequest: Author search request DTO.
  - `author_name` string, required: Author name to search for. Cannot be empty.
  - `not_author_name` string: Exclude articles written by this author name.
  - `sources` unknown
  - `predefined_sources` unknown
  - `not_sources` unknown
  - `lang` unknown
  - `not_lang` unknown
  - `countries` unknown
  - `not_countries` unknown
  - `from_` union: Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted.
    - string
    - string, date-time
  - `to_` union: End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted.
    - string
    - string, date-time
  - `published_date_precision` string: Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).
  - `by_parse_date` boolean: When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date.
  - `sort_by` string: Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first).
  - `ranked_only` union: When true, only returns articles from sources that have a known rank (excludes unranked sources).
    - string
    - boolean
  - `from_rank` integer: Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.
  - `to_rank` integer: Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.
  - `is_headline` union: Filter by whether the article was featured as a headline on its source's homepage at the time of parsing.
    - string
    - boolean
  - `is_opinion` union: Filter by whether the article is opinion/editorial content.
    - string
    - boolean
  - `is_paid_content` union: Filter by whether the article is behind a paywall or marked as sponsored/paid content.
    - string
    - boolean
  - `parent_url` unknown
  - `all_links` unknown
  - `all_domain_links` unknown
  - `all_links_text` unknown
  - `word_count_min` integer: Minimum article word count. Must be non-negative, and less than word_count_max if both are set.
  - `word_count_max` integer: Maximum article word count. Must be non-negative, and greater than word_count_min if both are set.
  - `page` integer: Page number of results to return, starting at 1.
  - `page_size` integer: Number of articles per page. Integer between 1 and 1000.
  - `include_nlp_data` boolean: For NLP-enabled plans, controls whether the nlp object is included in the response for each article (excluded by default). Basic plan always includes nlp.theme regardless of this setting.
  - `has_nlp` boolean: When true, only returns articles that have NLP enrichment data. Requires an NLP plan.
  - `theme` string: Filter by article theme. One of: Business, Politics, Entertainment, Sports, Finance, Crime, Tech, General, Health, Economics, Science, Automotive, Weather, Travel, Lifestyle, Financial Crime. Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article (e.g. 'Tech AND Finance,Sports' matches Tech-and-Finance articles, or Sports articles).
  - `not_theme` string: Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.
  - `title_sentiment_min` number: Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.
  - `title_sentiment_max` number: Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.
  - `content_sentiment_min` number: Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.
  - `content_sentiment_max` number: Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.
  - `iptc_tags` unknown
  - `not_iptc_tags` unknown
  - `iab_tags` unknown
  - `not_iab_tags` unknown
  - `include_translation_fields` union: Includes machine-translated title/content fields (title_translated_en, content_translated_en) in the response for non-English articles. Automatically enabled if search_in includes a '_translated' field.
    - string
    - boolean
  - `robots_compliant` union: Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones.
    - string
    - boolean

## Response `200`

Successful Response

- union
  - AuthorSearchResponse: AuthorSearchResponse DTO class.
    - `status` string: Always 'ok' for a successful search.
    - `total_hits` integer, required: Total number of articles matching the query, across all pages.
    - `page` integer, required: Current page number returned.
    - `total_pages` integer, required: Total number of pages available for this query, given page_size.
    - `page_size` integer, required: Number of articles returned per page.
    - `articles` object[], required: Articles matching the query for this page.
    - `user_input` object, required: Echo of the request parameters that produced this response.
  - FailedAuthorSearchResponse: FailedAuthorSearchResponse DTO class.
    - `status` string: Explains why no articles were returned.
    - `total_hits` integer: Always 0 - no articles matched the query.
    - `page` integer: Always 0 - no page of results was produced.
    - `total_pages` integer: Always 0 - no pages of results were produced.
    - `page_size` integer: Always 0 - no page size applies when there are no results.
    - `articles` AuthorSearchArticleResult[]: Always empty - no articles matched the query.
      - `title` string, required: Article headline/title.
      - `author` string: Author byline as a single string, as originally extracted from the source.
      - `authors` union: List of author names, parsed from the byline where possible.
        - string[]
        - string
      - `journalists` union: List of journalist names, where identified separately from the general author byline.
        - string[]
        - string
      - `published_date` string: Date and time the article was originally published.
      - `published_date_precision` string: Precision of published_date: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).
      - `updated_date` string: Date and time the article was last updated by its source, if known.
      - `updated_date_precision` string: Precision of updated_date, using the same scale as published_date_precision.
      - `parse_date` string: Date and time NewsCatcher parsed/ingested the article. Only included when by_parse_date is used in the request.
      - `link` string, required: Direct URL to the article.
      - `domain_url` string, required: Root domain of the article's source (e.g. 'bbc.com').
      - `full_domain_url` string, required: Full domain of the article's source, including subdomain (e.g. 'news.bbc.co.uk').
      - `name_source` string: Display name of the news source.
      - `is_headline` string: Whether the article was featured as a headline on its source's homepage at the time of parsing.
      - `paid_content` boolean: Whether the article is behind a paywall or marked as sponsored/paid content.
      - `extraction_data` string: Parent/section URL the article was discovered under (e.g. a category or tag page).
      - `country` string: Country of the article's source, as an ISO 3166-1 alpha-2 code.
      - `rights` string: Copyright/rights holder information, if available.
      - `rank` integer, required: Source rank - lower values indicate a more authoritative/popular source.
      - `media` string: URL of the article's main image, if available.
      - `language` string: Article language, as a two-letter ISO 639-1 code.
      - `description` string: Short summary or dek/subheading of the article, as extracted from the source.
      - `content` string, required: Full text content of the article.
      - `title_translated_en` string: Machine-translated English title, for non-English articles. Only included when include_translation_fields is used in the request.
      - `content_translated_en` string: Machine-translated English content, for non-English articles. Only included when include_translation_fields is used in the request.
      - `word_count` integer: Word count of the article content.
      - `is_opinion` boolean: Whether the article is opinion/editorial content.
      - `twitter_account` string: Twitter/X account associated with the source or author, if available.
      - `all_links` union: URLs linked to from within the article content.
        - string[]
        - string
      - `all_domain_links` union: Domains linked to from within the article content.
        - string[]
        - string
      - `all_links_data` unknown[]: Structured link data (URL and domain pairs) for links within the article content. Only included when all_links_text is used in the request.
        - unknown
      - `nlp` object: NLP enrichment data (sentiment, theme, named entities, tags), when available and permitted by your plan.
      - `id` string, required: Unique identifier for this article.
      - `score` number, required: Elasticsearch relevance score for this result, given the request's query and sort order.
      - `custom_tags` object: Organization-specific custom tags applied to this article, if your account has any configured.
    - `user_input` object, required: Echo of the request parameters that produced this response.

## Other responses

- `401`: Missing or invalid `x-api-token` header.
- `403`: A supplied parameter isn't included in your subscription plan, or the requested date range exceeds your plan's allowed history window. Also returned to free tier (trial) keys whose trial has ended or whose included calls are used up.
- `408`: Your query reached the search backend but did not finish within 30 seconds. Narrow the date range, lower page_size, or simplify the query. Note this covers only genuinely slow queries - if the backend could not be reached at all the response is 503, which is retryable as-is.
- `422`: Request validation failed, e.g. an invalid parameter value or a missing required field.
- `429`: Rate limit exceeded for your plan.
- `499`: The HTTP status line is 499, but the response body's own `status_code` field reads 422 - a known quirk of this API's validation-error handling for cases not covered by the standard 422 path, not a documentation error.
- `503`: The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.

---

[API](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api.md) - [All operations](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api/llms.txt) - [OpenAPI document](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api/revisions/a3950aefb3e5?raw)