# visitors.get

Detalhe do visitante. Um visitante com as sessões (e as ações de cada uma), o primeiro toque (origem e UTMs), o último IP e o contato vinculado. `not_found` quando o visitante não existe; sem rastreio no Atomiks, nenhum existe.

- Endpoint: `POST https://app.atomiks.com.br/api/v1/visitors.get` (corpo JSON)
- Quem pode chamar: membro da conta
- Escopo da chave: `contacts:read`
- Grava dados: não
- Pela chave de API: sim
- Ferramenta MCP: `visitors_get`
- Ficha em JSON: `https://app.atomiks.com.br/api/v1/openapi.json` (operationId `visitors.get`)

## Entrada

| Campo | Tipo | Obrigatório | Nota |
|---|---|---|---|
| `id` | string | sim |  |

<details><summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    }
  },
  "required": [
    "id"
  ]
}
```

</details>

## Exemplo

```bash
curl -X POST https://app.atomiks.com.br/api/v1/visitors.get \
  -H "Authorization: Bearer $ATOMIKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"vis_00000000"}'
```

CLI:

```bash
node cli/atomiks.mjs visitors.get --json '{"id":"vis_00000000"}'
```

MCP: ferramenta `visitors_get` com a mesma entrada.

## Saída

Sucesso: `{"data": ...}` com o formato abaixo.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "channel": {
      "type": "string",
      "enum": [
        "google",
        "facebook",
        "instagram",
        "tiktok",
        "youtube",
        "linkedin",
        "whatsapp",
        "email",
        "referral",
        "direct",
        "other"
      ]
    },
    "device": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "desktop",
            "mobile",
            "tablet",
            "unknown"
          ]
        },
        "os": {
          "type": [
            "string",
            "null"
          ]
        },
        "browser": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    },
    "firstSeenAt": {
      "type": "string"
    },
    "lastSeenAt": {
      "type": "string"
    },
    "sessionCount": {
      "type": "number"
    },
    "lastIpAddress": {
      "type": [
        "string",
        "null"
      ]
    },
    "sessions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "startedAt": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "google",
              "facebook",
              "instagram",
              "tiktok",
              "youtube",
              "linkedin",
              "whatsapp",
              "email",
              "referral",
              "direct",
              "other"
            ]
          },
          "utmCampaign": {
            "type": [
              "string",
              "null"
            ]
          },
          "utmSource": {
            "type": [
              "string",
              "null"
            ]
          },
          "utmMedium": {
            "type": [
              "string",
              "null"
            ]
          },
          "referrer": {
            "type": [
              "string",
              "null"
            ]
          },
          "landingUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "landingHostname": {
            "type": [
              "string",
              "null"
            ]
          },
          "landingPathname": {
            "type": [
              "string",
              "null"
            ]
          },
          "projectName": {
            "type": [
              "string",
              "null"
            ]
          },
          "clickIds": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "platform": {
                  "type": "string",
                  "enum": [
                    "meta",
                    "google",
                    "tiktok",
                    "microsoft"
                  ]
                },
                "param": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "platform",
                "param",
                "value"
              ],
              "additionalProperties": false
            }
          },
          "durationSeconds": {
            "type": "number"
          },
          "engagementSeconds": {
            "type": "number"
          },
          "maxScrollPercent": {
            "type": [
              "number",
              "null"
            ]
          },
          "eventCount": {
            "type": "number"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "eventType": {
                  "type": "string"
                },
                "occurredAt": {
                  "type": "string"
                },
                "pageName": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "formName": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "pathname": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "formStepId": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "id",
                "eventType",
                "occurredAt",
                "pageName",
                "formName",
                "pathname",
                "formStepId"
              ],
              "additionalProperties": false
            }
          },
          "hasMoreEvents": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "startedAt",
          "channel",
          "utmCampaign",
          "utmSource",
          "utmMedium",
          "referrer",
          "landingUrl",
          "landingHostname",
          "landingPathname",
          "projectName",
          "clickIds",
          "durationSeconds",
          "engagementSeconds",
          "maxScrollPercent",
          "eventCount",
          "events",
          "hasMoreEvents"
        ],
        "additionalProperties": false
      }
    },
    "hasMoreSessions": {
      "type": "boolean"
    },
    "firstTouch": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "startedAt": {
              "type": "string"
            },
            "channel": {
              "type": "string",
              "enum": [
                "google",
                "facebook",
                "instagram",
                "tiktok",
                "youtube",
                "linkedin",
                "whatsapp",
                "email",
                "referral",
                "direct",
                "other"
              ]
            },
            "utmCampaign": {
              "type": [
                "string",
                "null"
              ]
            },
            "utmSource": {
              "type": [
                "string",
                "null"
              ]
            },
            "utmMedium": {
              "type": [
                "string",
                "null"
              ]
            },
            "referrer": {
              "type": [
                "string",
                "null"
              ]
            },
            "landingUrl": {
              "type": [
                "string",
                "null"
              ]
            },
            "landingHostname": {
              "type": [
                "string",
                "null"
              ]
            },
            "landingPathname": {
              "type": [
                "string",
                "null"
              ]
            },
            "projectName": {
              "type": [
                "string",
                "null"
              ]
            },
            "clickIds": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": [
                      "meta",
                      "google",
                      "tiktok",
                      "microsoft"
                    ]
                  },
                  "param": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string"
                  }
                },
                "required": [
                  "platform",
                  "param",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "durationSeconds": {
              "type": "number"
            },
            "engagementSeconds": {
              "type": "number"
            },
            "maxScrollPercent": {
              "type": [
                "number",
                "null"
              ]
            },
            "eventCount": {
              "type": "number"
            },
            "events": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "eventType": {
                    "type": "string"
                  },
                  "occurredAt": {
                    "type": "string"
                  },
                  "pageName": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "formName": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "pathname": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "formStepId": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "id",
                  "eventType",
                  "occurredAt",
                  "pageName",
                  "formName",
                  "pathname",
                  "formStepId"
                ],
                "additionalProperties": false
              }
            },
            "hasMoreEvents": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "startedAt",
            "channel",
            "utmCampaign",
            "utmSource",
            "utmMedium",
            "referrer",
            "landingUrl",
            "landingHostname",
            "landingPathname",
            "projectName",
            "clickIds",
            "durationSeconds",
            "engagementSeconds",
            "maxScrollPercent",
            "eventCount",
            "events",
            "hasMoreEvents"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "lead": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": [
                "string",
                "null"
              ]
            },
            "email": {
              "type": [
                "string",
                "null"
              ]
            },
            "linkedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name",
            "email",
            "linkedAt"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id",
    "channel",
    "device",
    "firstSeenAt",
    "lastSeenAt",
    "sessionCount",
    "lastIpAddress",
    "sessions",
    "hasMoreSessions",
    "firstTouch",
    "lead"
  ],
  "additionalProperties": false
}
```

## Erros

`{"error": {"code", "message", "requestId"}}`. Códigos: `invalid_input` (400), `unauthorized` (401), `forbidden` / `account_pending` / `scope_missing` (403), `not_found` (404), `limit_reached` (409), `internal` (500).