---
title: "Agent profile. Registry: agents.by-id"
method: GET
path: "/madlan/agent"
tags: ["Madlan"]
---

# Agent profile. Registry: agents.by-id

`GET /madlan/agent`

## Request

- Base URL: `https://scrappa.co/api`
- URL: `https://scrappa.co/api/madlan/agent`
- Auth: API key in header `X-API-KEY`

## Query parameters

- `id` string, required

## Response `200`

- union
  - object
    - `success` boolean, required
    - `found` boolean, required
    - `agent` string, nullable, required
    - `meta` union, required
      - string
      - string[]
  - object
    - `success` boolean, required
    - `found` boolean, required
    - `agent` unknown, required
    - `notes` unknown[], required
      - unknown
    - `meta` union, required
      - string
      - string[]
  - object
    - `success` boolean, required
    - `data` string, nullable, required
    - `meta` object, required
      - `attempts` integer, required
      - `duration_ms` string, required
  - object
    - `success` boolean, required
    - `error` object, required
      - `code` 'unexpected_response_shape', required
      - `message` 'Madlan returned an unexpected response.', required
      - `http_status` 502, required
      - `retryable` boolean, required
    - `meta` object, required
      - `attempts` integer, required
      - `duration_ms` integer, required
  - object
    - `success` boolean, required
    - `error` object, required
      - `code` 'upstream_rejected', required
      - `message` 'Madlan rejected this query.', required
      - `http_status` 502, required
      - `retryable` boolean, required
    - `meta` object, required
      - `attempts` integer, required
      - `duration_ms` integer, required
  - object
    - `success` boolean, required
    - `error` object, required
      - `code` 'upstream_unavailable', required
      - `message` 'Madlan is temporarily unavailable. Please retry.', required
      - `http_status` 502, required
      - `retryable` boolean, required
    - `meta` object, required
      - `attempts` integer, required
      - `duration_ms` integer, required
  - object
    - `success` boolean, required
    - `error` object, required
      - `code` 'upstream_request_rejected', required
      - `message` 'Madlan rejected this request.', required
      - `http_status` 502, required
      - `retryable` boolean, required
    - `meta` object, required
      - `attempts` integer, required
      - `duration_ms` integer, required
  - object
    - `success` boolean, required
    - `error` object, required
      - `code` 'upstream_unavailable', required
      - `message` 'Madlan is temporarily unavailable. Please retry.', required
      - `http_status` 503, required
      - `retryable` boolean, required
    - `meta` object, required
      - `attempts` integer, required
      - `duration_ms` integer, required
  - object
    - `success` boolean, required
    - `error` object, required
      - `code` 'rate_limited_upstream', required
      - `message` 'Madlan is temporarily unavailable. Please retry.', required
      - `http_status` 503, required
      - `retryable` boolean, required
    - `meta` object, required
      - `attempts` integer, required
      - `duration_ms` integer, required
  - object
    - `success` boolean, required
    - `error` object, required
      - `code` 'unsafe_operation_name', required
      - `message` 'Madlan returned an unexpected response.', required
      - `http_status` 502, required
      - `retryable` boolean, required
    - `meta` object, required
      - `attempts` integer, required
      - `duration_ms` integer, required
  - string

## Other responses

- `401`: Unauthorized - API key is missing or invalid
- `404`: The id is well-formed and Madlan answered, but nothing is published under it. The body carries `found => false`. The lookup was answered, so it is billed; unlike a 503 this is not an upstream fault and retrying will not change it.
- `422`: One or more parameters are missing, out of range, or a filter Madlan cannot apply. Filters it cannot apply are refused rather than ignored, so the response never carries the unfiltered corpus in answer to a filter. The response lists the...
- `503`: Madlan answered the request but refused to compute it. Branch on `error.code`: this response is not retryable. Nothing is charged for a failed request. Madlan answered with a client-side rejection before running the query, for example a...

---

[API](https://skmtc.dev/scrappa/apis/scrappa-api-documentation.md) · [All operations](https://skmtc.dev/scrappa/apis/scrappa-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/scrappa/apis/scrappa-api-documentation/revisions/1e1aa78ff103?raw)