Create a search

Returns a job_id with status queued. Use it to get your search results.

Send Authorization: Bearer with a dashboard API key. A rejected key returns 401 invalid_api_key and does not create a search. See API keys.

The 202 body includes usage.estimated_cost, the maximum USD charge for these options after your subscription discount, and usage.discount_percent. actual_cost is null until the search finishes. If your credit balance cannot cover the estimate, the response is 402 insufficient_balance and no search is created. See Credits and pricing.

Each API key can create 10 searches per minute and 100 per hour. Over that, the response is 429 rate_limit_exceeded with Retry-After, and no search is created. See API keys.

curl -X POST "https://example.com/search" \  -H "Content-Type: application/json" \  -d '{    "text": "string"  }'

{  "job_id": "src_example",  "status": "queued",  "usage": {    "currency": "USD",    "estimated_cost": 0.005,    "actual_cost": null,    "discount_percent": 0,    "balance_after": null  }}

Request optionsCopy Anchor Link

• mode picks the search depth. quick searches one Google Scholar page per search phrase. deep searches widely, shortlists the 15 most promising sources, reads them in full and ranks them twice, which usually takes about three minutes. See How search works.
• Set enrichment: "none" to skip analysis. If omitted, quick search uses medium and deep search uses high.
• There is no page-size field. A page is one provider results page per search phrase, so a quick search returns up to 20 sources, or 30 for texts over 3000 characters, and a deep search returns up to 15.
• Use filters to narrow results by year, citations, keywords, domains and more.
• Unknown request fields return 422, including the removed max_sources.

FiltersCopy Anchor Link

filters is an optional object. Omit it, send null, or send an empty object to search without additional filter constraints. Every field below is optional and defaults to null. Unknown filter names are rejected with HTTP 422.

Active filters are combined: a source must pass every local condition. Filters narrow the available results, so a successful search may return fewer than a full page, or none. Some filters also affect provider retrieval; the differences are explained below.

year_fromCopy Anchor Link

Type: integer or null. Example: 2020.

Keep papers published in 2020 or later. The boundary is inclusive. Papers with an unknown publication year are excluded when this filter is active. Omit it or use null to leave the lower bound open.

year_toCopy Anchor Link

Type: integer or null. Example: 2024.

Keep papers published in 2024 or earlier, including 2024 itself. Unknown publication years are excluded when this filter is active. Omit it or use null to leave the upper bound open.

Together, "year_from": 2020 and "year_to": 2024 select 2020–2024 inclusive. Set the lower bound no higher than the upper bound. The current model accepts integers without validating the order or imposing a calendar-year range; an inverted range cannot match a known publication year.

min_citationsCopy Anchor Link

Type: integer greater than or equal to 0, or null. Example: 10.

Keep sources with at least 10 citations according to available provider metadata. This is a citation-count threshold, not a relevance score or a guarantee of quality.

Unknown counts are treated as zero during filtering: they pass 0, but fail any positive threshold. Omit the field or use null for no citation-count restriction. Negative values return HTTP 422.

open_accessCopy Anchor Link

Type: boolean or null. Example: true.

With true, keep only sources whose metadata contains a non-empty pdf_url. The API does not verify that the PDF is downloadable or confirm its license, so this currently indicates PDF availability in the metadata.

false, null and omission all disable this filter. false does not select closed-access papers.

paper_typesCopy Anchor Link

Type: array of "research" and/or "review", or null. Example: ["review"].

Values are case-sensitive; unsupported values return HTTP 422. Classification uses text heuristics and provider hints. It does not independently verify the publication type or peer-review status, and it is separate from the returned enrichment classification.

venueCopy Anchor Link

Type: string or null. Example: "Nature".

Ask supporting providers to restrict retrieval to a journal or publication venue. Use a venue name, not an article title or a URL.

Currently, this hint is sent to Semantic Scholar and providers using Scholar search URLs. The Serper adapter does not forward it, and the API does not apply an exact venue match after retrieval. Results can therefore include other venues. Omit it, use null, or use an empty string to disable the hint.

include_keywordsCopy Anchor Link

Type: array of strings or null. Example: ["sleep", "memory"].

Require all entries to appear somewhere in the combined title, abstract and venue metadata. They may appear in different fields. Matching is case-insensitive and uses literal substrings, so "sleep" can match "sleeping". It does not search the full paper or expand synonyms.

Google Scholar also receives each entry as a separate quoted phrase that every result must contain. Provider retrieval can therefore be stricter than the local all-keywords check.

Omit it, use null, or use [] to disable this filter. Entries are trimmed, and empty entries are ignored.

exclude_keywordsCopy Anchor Link

Type: array of strings or null. Example: ["mouse", "rat"].

Exclude a source if any entry appears in its combined title, abstract or venue metadata. Matching is case-insensitive and uses substrings: "rat" can also match a longer word containing those letters. Choose terms carefully when you need precise exclusions.

Omit it, use null, or use [] to disable this filter. An empty string matches every source and would exclude everything. If a source matches both an included and an excluded term, the exclusion wins. Full-paper text is not inspected.

include_domainsCopy Anchor Link

Type: array of strings or null. Example: ["ncbi.nlm.nih.gov"].

Return only sources whose url or pdf_url is on one of these domains or their subdomains. "ncbi.nlm.nih.gov" also matches pubmed.ncbi.nlm.nih.gov. You can pass bare host names or full URLs; the scheme, www. and any path are ignored. Google Scholar also receives matching site: operators.

Sources without a URL are excluded while this filter is active. Omit it, use null, or use [] to disable it.

exclude_domainsCopy Anchor Link

Type: array of strings or null. Example: ["wikipedia.org"].

Drop any source whose url or pdf_url is on one of these domains or their subdomains, so "wikipedia.org" also removes en.wikipedia.org. Entries are normalized like include_domains, and Google Scholar receives matching -site: operators. Omit it, use null, or use [] to disable it.

preferred_domainsCopy Anchor Link

Type: array of strings or null. Example: ["ncbi.nlm.nih.gov", "nature.com"].

Move sources from these domains ahead of the rest, most preferred first. Unlike include_domains, other domains still appear. Within each group the normal order is kept. Omit it, use null, or use [] to keep the normal order only.

Example request with filtersCopy Anchor Link

This request looks for recent papers containing both “sleep” and “memory” in their metadata, with at least ten citations, while excluding the phrase “case report”. Add open_access, paper_types or venue only when you need those additional restrictions.

{
  "text": "How does sleep affect memory consolidation?",
  "mode": "quick",
  "enrichment": "none",
  "filters": {
    "year_from": 2020,
    "year_to": 2025,
    "min_citations": 10,
    "include_keywords": ["sleep", "memory"],
    "exclude_keywords": ["case report"]
  }
}

Response and value referenceCopy Anchor Link

• JobAccepted fields
• SearchRequest and filters
• All enums
• Validation and other errors

HTTP 402 insufficient_balance means the account's credits cannot cover estimated_cost. The body says why. Add credits on the API and MCP page in Sourcely, or turn on automatic top-up:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Prepaid balance is below the estimated cost of this search.",
    "details": { "estimated_cost": 0.165, "credits_remaining": 0.04 }
  }
}

webhook_url receives a POST when the search finishes. See Webhooks. Polling still returns the result.