Create a chart

POSThttps://api.typesearch.ai/v1/charts

Plans what to measure, searches for it and draws a card with the key figures, a title that states the finding, annotations and the source of every value. Or send data (series, events, or columns and rows) and get the same card from your own numbers. Send query or data, not both. The Charts guide explains every recipe, type and rule.

It answers 201 Created with a new chart, and 200 OK with plan_only, with store: false, or when the same request within 10 minutes returns the same chart (cached: true, not billed). When the search doesn't find enough data it answers 422 insufficient_data, not billed.

From a query it costs its search (the mode it needed, per query) plus $0.50 per 1,000 charts; from your data, $0.30 per 1,000. See pricing.

Body

querystring
What you want to see, in plain words and any language: "blue dollar this week", "Milei vs Bullrich coverage", "which outlets cover lithium", or "prices" with index. 2–200 characters. Send query or data, not both.
dataobject
Your own data instead of a query, with no search: series of points, events for a timeline, or columns and rows for a table, plus optional formats for the axes (x, y, x_measure) and a highlight.
Series of points, events, or columns and rows. See From your own data in the Charts guide.
typeenum<string>Default: "auto"
The chart type. auto picks the one that tells the data best. Any other is respected while the data allows it; if not, the closest type that fits is drawn, with a chart_type_adjusted warning.
One of: auto · line · area · bar · bar_horizontal · stacked_bar · pie · donut · scatter · funnel · timeline · kpi · table
indexstring
Build the chart from your custom index (idx_…) instead of the news: prices, price against rating, availability or brands, from the data each page declares. No date filter unless you set one.
modeenum<string>Default: "auto"
auto uses the cheapest mode that gets the data: ultra for coverage, share of voice and outlets, fast for the rest, and normal when the figures aren’t in headlines and standfirsts. Or fix it to ultra, fast, normal or deep. The chart is billed in the mode it ends in.
comparestring[]
What to compare, 2 to 5 names, when the query doesn’t say it with "vs". Each name is searched, and billed, as its own query.
Items: up to 5
questionsmap<string, …>
One typed question (boolean, choice or score), in the same format as in search: the chart shows how the answers split across the articles.
daysinteger | null
The last N days, 1–365. By default it depends on the recipe: 30 for coverage, 7 for figures, the whole index with index (see the Charts guide). A date in the query, published_after or published_before set the period instead.
Range: 1–365
published_afterdate | date-time
Published on or after this moment. A bare date (2026-09-20) covers the whole day in UTC−3; a date-time needs an offset.
published_beforedate | date-time
Published on or before this moment, inclusive. Same format as published_after.
countriesstring[]
Only sources based in these countries: ISO 3166-1 alpha-2 codes, such as AR or US.
Items: up to 50
languagesstring[]
Only sources that publish in these languages: ISO 639-1 codes, such as es or en. A tag such as pt-BR counts as pt.
Items: up to 20
include_domainsstring[]
Only these domains or paths, up to 20. A domain includes its subdomains.
Items: up to 20
exclude_domainsstring[]
Never these domains or paths, up to 20.
Items: up to 20
timezonestring
The IANA time zone that decides what day "today" is and where each day starts, such as America/Mexico_City. Defaults to America/Argentina/Buenos_Aires.
titlestring
Your title. Without one, the chart gets a title that states the finding.
subtitlestring
Your subtitle. Without one, a chart from a query says what was measured and over which period.
sourcestring
The source line in the footer, for your own data.
themeenum<string>Default: "light"
light (the default), dark, editorial (warm paper, for media) or electric (deep blue, for slides). Switch it later with PATCH, or per view with ?theme=.
localeenum<string>
The language of titles, labels and numbers: en or es. Defaults to the Accept-Language header.
plan_onlybooleanDefault: false
Return only the plan (what would be measured, the chart type and the data it needs) without searching or drawing. Free.
storebooleanDefault: true
false stores nothing: no id and no URLs, and the SVG comes in svg. Same price.
include_svgbooleanDefault: false
Also return the SVG in svg for a stored chart.

Response

idstring | null
The chart id, chart_…. null with store: false or plan_only.
object"chart"
Always chart.
typeenum<string> | null
The chart type that was drawn. null with plan_only.
One of: line · area · bar · bar_horizontal · stacked_bar · pie · donut · scatter · funnel · timeline · kpi · table
themeenum<string>
The theme it is drawn in.
One of: light · dark · editorial · electric
localeenum<string>
The language of titles, labels and numbers.
One of: en · es
chartobject | null
What is drawn: the series and their points, the key figures on top, annotations, events or rows, and a title that states the finding. null with plan_only.
Series (series[].points[] with x, y and sources), kpis, annotations, events, columns and rows, and how each axis is formatted (x, y, x_measure).
compatible_typesenum<string>[]
Every chart type this data supports, best first. Switch among them for free with PATCH.
One of: line · area · bar · bar_horizontal · stacked_bar · pie · donut · scatter · funnel · timeline · kpi · table
planobject | null
From a query: what was measured (recipe), why this chart, other types that fit, and the data it needed. null for your own data.
The recipe, type, alternatives (with their probability), topic, entities and needs (queries, mode, days, min_points, max_results).
sourcesobject[]
The articles behind the chart. Each point’s sources are indexes in this list. Empty for your own data.
Show child attributes
- urlstring
  The article’s URL.
- titlestring
  Its headline.
- sourcestring | null
  The outlet’s name.
- published_atstring | null
  When it was published.
embed_urlstring | null
A page for an iframe: it adapts to its width and shows tooltips. Public, no key needed. Add ?theme= for another theme. null when nothing is stored.
image_urlstring | null
The PNG at twice the resolution, for chat, email or slides. Add ?size=compact for the narrow layout.
svg_urlstring | null
The SVG. Add ?size=compact for the narrow layout.
svgstring | null
The SVG itself, with include_svg or store: false. Otherwise null.
created_atstring | null
When it was created.
expires_atstring | null
When it expires: 90 days after it was created on pay as you go. null on the monthly credit plan, where it never does.
cachedboolean
true when the same request in the last 10 minutes returned the same chart. Not billed.
usageobject
What the request cost.
Show child attributes
- cost_usdnumber
  Cost in US dollars: the search in its mode, per query, plus the chart add-on; or the price of a chart from your data. 0 when cached, and on GET and PATCH.
- modeenum<string> | null
  The mode it was billed in, or data for your own data. null when nothing was billed.
  One of: ultra · fast · normal · deep · data
- queriesinteger
  How many queries were searched: one per name in a comparison.
  Range: -9007199254740991–9007199254740991
- duration_msinteger
  Time on the server, in milliseconds.
  Range: -9007199254740991–9007199254740991
warningsobject[]
Notes that didn’t stop the chart: chart_type_adjusted, grouped or indexed.
Show child attributes
- codestring
  A stable code.
- messagestring
  A human-readable explanation.

curl https://api.typesearch.ai/v1/charts \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "which outlets cover lithium",
    "theme": "editorial"
  }'

201 Created (abridged)

{
  "id": "chart_3v7n1q8m2k5x9w4p",
  "object": "chart",
  "type": "bar_horizontal",
  "theme": "editorial",
  "locale": "en",
  "chart": {
    "type": "bar_horizontal",
    "title": "Diario Ejemplo published the most about lithium",
    "subtitle": "Articles mentioning lithium, per outlet · Aug 28–Sep 26",
    "x": { "kind": "category" },
    "y": { "format": "number", "label": "articles" },
    "part_of_whole": true,
    "series": [
      {
        "name": "Articles",
        "points": [
          { "x": "Diario Ejemplo", "y": 42 },
          { "x": "Noticias Ejemplo", "y": 31 },
          { "x": "La Crónica Demo", "y": 27 }
        ]
      }
    ]
  },
  "compatible_types": ["bar", "bar_horizontal", "donut", "pie", "kpi", "table"],
  "plan": {
    "recipe": "outlets",
    "measure": "outlets",
    "x_axis": "outlet",
    "type": "bar_horizontal",
    "part_of_whole": true,
    "confidence": 1,
    "alternatives": [
      { "type": "bar", "probability": 0 },
      { "type": "donut", "probability": 0 },
      { "type": "pie", "probability": 0 }
    ],
    "topic": "lithium",
    "entities": [],
    "needs": { "queries": ["lithium"], "mode": "ultra", "days": 30, "min_points": 1, "max_results": 10 }
  },
  "sources": [
    {
      "url": "https://diario.example/economia/litio-exportaciones",
      "title": "Lithium exports hit a record in August",
      "source": "Diario Ejemplo",
      "published_at": "2026-09-25T11:20:00Z"
    }
  ],
  "embed_url": "https://api.typesearch.ai/embed/chart_3v7n1q8m2k5x9w4p",
  "image_url": "https://api.typesearch.ai/embed/chart_3v7n1q8m2k5x9w4p.png",
  "svg_url": "https://api.typesearch.ai/embed/chart_3v7n1q8m2k5x9w4p.svg",
  "svg": null,
  "created_at": "2026-09-26T14:02:11.482Z",
  "expires_at": "2026-12-25T14:02:11.482Z",
  "cached": false,
  "usage": { "cost_usd": 0.0015, "mode": "ultra", "queries": 1, "duration_ms": 910 },
  "warnings": []
}

Body: your own data

{
  "data": {
    "series": [
      {
        "name": "Share",
        "points": [
          { "x": "Search", "y": 46 },
          { "x": "Social", "y": 31 },
          { "x": "Direct", "y": 23 }
        ]
      }
    ],
    "y": { "format": "percent" }
  },
  "title": "Where our readers come from",
  "source": "Diario Ejemplo analytics"
}