dataz.md

Telegram API reference

Search messages across Telegram chats

Crawlable reference for GET /messages/search through a dataz.md tenant gateway.

Purpose

GET/messages/search

Search Telegram with its native server-side message search.

Omitting `chat_id runs one messages.searchGlobal request across every accessible dialog, so broad discovery costs a single call rather than a history fetch per chat. Author filters are the exception: searchGlobal has no sender field, so they require chat_id`.

Category: Messages Auth: Authorization bearer or X-API-Key Scope: read-only

Authentication

Send a tenant API key as Authorization: Bearer <key> or X-API-Key: <key>. Keep keys server-side and use the account slug for the connected Telegram account.

Read the gateway authentication tutorial.

Parameters

NameInRequiredType / constraints
content query optional string · default null
author_id query optional integer · default null
author_username query optional string · default null
chat_id query optional integer · default null
topic_id query optional integer · default null
before query optional integer · default null
before_date query optional string · default null
limit query optional integer · default 50 · range 1–100

Request example

Replace the tenant, account, and resource placeholders before running this read-only request.

curl --fail-with-body \
  -H "Authorization: Bearer ${DATAZ_API_KEY}" \
  "https://dataz.md/gateway/v1/{tenant_slug}/accounts/{account_slug}/messages/search?limit=100"

Response schema

Documented responses
200Response model: JSON responseobject

Response example

Representative JSON shape. The live response can include additional documented fields.

{
  "results": [
    {
      "id": "7600000001",
      "content": "Example matching message",
      "type": 0,
      "timestamp": "2026-05-26T18:00:00+00:00",
      "channelId": "7200000001",
      "chat_id": "7200000001",
      "chat_name": "dataz.md Mock Group",
      "matched_field": "content",
      "matched_text": "Example matching message",
      "matched_hidden_metadata": false,
      "author": {
        "id": "7400000001",
        "username": "avery_mock",
        "name": "Avery Mock"
      }
    }
  ],
  "authors": [
    {
      "id": "7400000001",
      "username": "avery_mock",
      "name": "Avery Mock"
    }
  ],
  "scope": "chat",
  "searched": [
    "7200000001"
  ],
  "coverage": {
    "mode": "single_chat",
    "searched_chat_count": 1,
    "matched_chat_count": 1,
    "skipped_chat_count": 0
  },
  "skipped": [],
  "cursor": null,
  "cursor_field": null,
  "partial": false
}

Errors

Common responses
401Missing or invalid tenant API key.authentication
403The tenant, account, or connected provider cannot access the requested resource.authorization
404The route or requested provider resource was not found.not found
422A path or query parameter is invalid.validation
429Rate limited; wait for the Retry-After interval before retrying.rate limit

Limits and pagination

  • Use limit to bound each response; it defaults to 50 and accepts 1–100.
  • Use before to continue toward older records or after for incremental reads; store source IDs as cursors.
  • Provider or demo limits can return HTTP 429. Wait for the Retry-After interval before retrying.

Related tutorials

Read-only notes

This reference page documents a public GET endpoint. Setup/token, AI, dev, internal, and mutating routes are excluded from static reference generation.